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About This Guide 


Purpose 


This document is a guide for programming using the Communications Management 
System (COMS). The purpose of the guide is the following: 


e To explain the various COMS features available to the programmer 


e To outline how to program using the features available in COMS 


The COMS product is a member of the InterPro (Interactive Productivity) Series of 
products designed for use with the Unisys A Series systems. 


Scope 
In this guide you can find information on programming for direct-window programs and 
remote-file programs. You can also find information on service functions, processing 
items, interactive and batch recovery, and security. 
This guide does not include information on migrating from one release to another. For 


information on compatibility issues across releases, refer to the applicable release in the 
A Series Mark 3.9 Software Release Capabilities Overview. 


Audience 


This guide is intended for experienced applications programmers. 


Prerequisites 


Programmers should be proficient in the programming language they are using 

to write COMS application programs. They should also have a knowledge of data 
communications subsystems. If the application program is updating a Data Management 
System II (DMSII) database or a Semantic Information Manager (SIM) database, the 
programmer should have knowledge of DMSII or SIM database processing. 


SIM is a member of the InfoExec™ family of products. The programmer should also be 
aware of the content of the COMS configuration file. 


InfoExec is a trademark of Unisys Corporation. 
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_ How to Use This Guide 


You should start by reading the overview to familiarize yourself with the features 
available through COMS. Separate sections of the guide are devoted to communicating 
with COMS through direct windows or remote-file windows. Each feature of COMS is 
presented in a separate chapter. The appendixes provide sample programs and quick — 
reference to the meanings of messages your program receives. A glossary defines 
terminology related to COMS, and acronyms that appear in this guide are spelled out 
and defined in the glossary. 


Manuals relevant to this product are given their full titles in the “Related Product 
Information” portion of this preface. In text, manuals are first referenced by their 
full titles and subsequent references use a shortened version of their titles. Unless 
otherwise specified, manuals referred to in the text are for A Series machines. 


Organization | 
 _ This guide is organized as follows: 


Section 1. Introduction to COMS 


This section introduces the COMS concepts and features, as they relate to programming. 


Section 2. Creating Your COMS Application 


This section outlines decisions that are important toa COMS programmer in developing 
applications through the use of the windows available in COMS. 


Section 3. Communicating with COMS through Direct Windows 


This section discusses how to use direct-window programs to receive and send messages 
involving COMS. Descriptions of the input and output header fields are provided, along 
with information on message-routing techniques. 


Section 4. Accessing Service Functions 


This section describes the service functions or entry points that COMS provides to allow 
you to obtain information on all configuration file entities. 


Section 5. Processing Items 


This section provides instructions for creating your own message control system 
(MCS) features in the form of separate modules called processing items that reside in 
processing-item libraries. 
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Section 6. Interactive Recovery 


This section describes a method for writing programs that update databases and the 
behavior of those programs when reprocessing transactions after processing has been 
interrupted. 


Section 7. Batch Recovery 


This section describes a method for writing batch-oriented programs that update 
databases and the behavior of those programs when reprocessing transactions after 
processing has been interrupted. 


Section 8. Security 


This section provides information on the security-checking routines that you can write 
into application programs and processing items to augment COMS security or to function 
independently. 


Section 9. Communicating with COMS through Remote-File Windows 


This section describes the various types of remote-file windows and how they are used. 


Appendix A. Tables of Values and Mnemonics 


This appendix provides quick-reference access to the meanings of message values 
returned to your program and lists associated mnemonics. 


Appendix B. COMS Header Layout 
This appendix shows the layout of the COMS Header fields and attributes. 


Appendix C. Sample COBOL74 Programs 


This appendix provides sample programs that illustrate the use of various COMS 
features. 


Appendix D. Sample Processing Items 


This appendix contains two sample processing items and the set of global declarations 
that these processing items require. 


Appendix E. Sample COBOL74-Processing Item Interface 


This appendix contains a sample COBOL74 program that can be used to write processing 
items by interfacing with an ALGOL shell. 


Appendix F. Service Functions for Previous Releases 


This appendix presents service functions to be used with previous releases of COMS. 
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In addition, a glossary, a bibliography, and an index appear at the end of this guide. 


Related Product Information 


The information in this guide is supplemented by the following documents, which pertain . 
to COMS: 


_ A Series Communications Management System (COMS) Capabilities Manual 
(form 8600 0627) 


This manual introduces COMS, discusses the flexibility and efficiency of the COMS 
system, describes the COMS architecture, and discusses specific features available to the 
COMS user. This manual is written for upper management, the site manager, and the 
programming staff. 


A Series Communications Management System (COMS) Configuration Guide 
(form 8600 0312) 


This guide provides an overview of the basic concepts and functions of COMS. It includes 
instructions for creating a working COMS configuration and information on how to 
monitor and fine-tune COMS system performance. This guide is written for installation 
analysts, systems analysts, programmers, administrators, and performance analysts. 


A Series Communications Management a (COMS) Migration Guide (form 
8600 1567) 


This guide explains how to migrate from existing message control systems (MCSs) to the 
current release of COMS. This guide is written for system administrators and system 
programmers who are responsible for the migration of their site to COMS. 


A Series Communications Management System (COMS) Operations Guide 
(form 8600 0833) 


‘This guide explains how to perform terminal-based COMS functional tasks and serves as 
a reference to COMS commands. Syntax diagrams of COMS commands are provided 
with explanations and examples of how the commands can be used. This guide is written 
for terminal operators and computer operators. 
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Section 1 
Introduction to COMS 


The Unisys Communications Management System (COMS) provides you with an 
extremely flexible and dynamic message control system (MCS) for the Unisys A Series 
systems. 


COMS Versions 


Two versions of COMS are available to you, and both use the COMS configuration file 
(which defines the characteristics of the COMS network) to provide the message control 
environment. 


COMS (Full-Featured) enables you to manipulate the configuration file by using the 
COMS Utility program. Additional features that you receive and can control directly 
are processing, routing, and some security features. 


The full-featured version of COMS also enables you to develop applications by using 
the transaction code (trancode) routing feature, the trancode security feature, the 
statistics feature, and the synchronized recovery feature for Data Management 
System II (DMS) and Semantic Information Manager (SIM) databases. 


COMS (Kernel) creates a predefined configuration file, which cannot be 
manipulated. The COMS (Kernel) configuration file enables you to use the window 
feature with four windows: a Menu-Assisted Resource Control (MARC) window 
with eight dialogues, a Command and Edit (CANDE) window with two dialogues, a 
Generalized Message Control System (GEMCOS) window with one dialogue, and a 
printing window used to support the Remote Print System (ReprintS). Additionally, 
you can communicate with remote-file programs. 


COMS Features 


The main features that you should be familiar with before using COMS are 


Windows 

Message processing 
Message routing 
Security 

Statistics window 


Database recovery 
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Windows 


COMS allows you to execute multiprogram environments from one station. Each 
program environment is referred to as a window. Windows do not allow you to see 
several program environments at the same time, but instead to move from one program 
environment to another while processing continues uninterrupted. 


Thus, if payroll, accounts receivable, and inventory control applications are defined in 
separate windows, an entry clerk with the appropriate security clearances could run 

a payroll data entry application in one window, an accounts receivable application in 
another, and an inventory control application in a third window. This clerk could move 
from window to window without having to wait for processing in each window to stop. 


Additionally, the window feature allows you to have up to eight dialogues in each defined 
window. A dialogue is a single access point into a given program environment (window). 
With multiple dialogues of a single window, the data entry clerk (who perhaps works 

for a service bureau and needs to concurrently process six customers using a single 
accounts receivable application) can change freely from one customer’s dialogue to - 
another without interrupting the processing in other copies of the accounts receivable 
application. | 


COMS provides three kinds of windows: 


° Direct windows 
e MCS windows 


e Remote-file windows 


A direct window allows you to route messages to programs defined to COMS while using 


all of COMS preprocessing and postprocessing capabilities. An MCS window provides 
access to a subordinate message control system, such as CANDE or GEMCOS. A 
remote-file window is a window established by COMS to allow programs to communicate 
interactively with data communication stations (remote files). 


Declared remote files are defined in the configuration file, while dynamic remote files are 
opened by COMS to provide access to programs that are not defined in the configuration 
file. 


For information about creating, modifying, and deleting windows in your COMS 
environment, refer to the A Series Communications Management System (COMS) 
Configuration Guide. For information on how to move from window to window, refer to 
the A Series Communications Management System (COMS) Operations Guide. 


Message Processing 


Direct windows provide considerable flexibility and processing power. COMS 

provides two ways of processing data found in direct window messages: by means of 
direct-window programs and by using processing items. You can arrange these methods 
in different sequences and use them to complement each other. 
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A direct-window program can be written in ALGOL, COBOL74, Pascal, or RPG, and can 
manipulate message data. All these languages, except Pascal, can be used to update 
DMSII and SIM databases. For more information about DMSII, see the A Series DMSII 
Application Program Interfaces Programming Guide. For more information about SIM, 
see the A Series Infokxec Semantic Information Manager (SIM) Object Manipulation 

| Language (OML) Programming Guide. 


A processing item is written in ALGOL and typically addresses a unique task that can 
be used by multiple applications and can be used many times within an application. For 
example, if your site requires that certain audits be done on all messages sent through 
the system, you can program that task in a processing item so that all applications 
developed in the COMS direct-window environment can use this processing item. 


Processing items can be used to preprocess messages before they reach a direct-window 
program and postprocess messages after they leave a direct-window program. For 
example, you can use preprocessing to format a menu of an application, while you might 
use postprocessing to format and print a bill. 


For information about COMS direct-window programming techniques and how to 
write processing items, refer to Section 5, “Processing Items,” in this guide and to the 
A Series ALGOL Programming Reference Manual, Volume 2: Product Interfaces. For 
information on how to define processing items, see the COMS Configuration Guide. 


For MCS and remote-file windows, COMS passes messages directly to and from the MCS 
or remote file. 


Message Routing 


COMS provides two methods of routing direct-window messages: the agenda method 
and the specific destination method. 


An agenda is a mechanism for routing and processing messages. Processing items 
become a part of an agenda by associating them with an agenda in the configuration file. 
If you use an agenda to control message routing, you can send a message to that agenda 
for processing (or routing) before it reaches or after it leaves a direct-window program. 


Trancodes can also be associated with an agenda. Trancodes are available only with the 
full-featured version of COMS. A trancode is a message identifier that can be used by 
COMS or by user applications to differentiate one message type from another. Thus, if 
INQ is the trancode for inquiry in a given application window, any message given that 
trancode would be routed to the agenda associated with that trancode. This method 

of routing is called trancode routing or transaction-based routing (TBR). One of the 
advantages of using trancodes for routing is that trancodes enable a direct window to 
have agendas assigned to it for various processing and routing requirements. 


The specific destination method is used by direct-window programs that directly identify 
output message destinations. This provides you with additional flexibility by allowing 
you to change the agenda destination at run time to direct the message to a different 
destination. 
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For information about defining agendas and trancodes, refer to the COMS Configuration 
Guide. 


For information about applying an agenda to a message or specifying a destination in a . 
direct-window program, refer to Section 3, “Communicating with COMS through Direct 
Windows.” | 


For MCS and remote-file windows, COMS passes messages directly to and from the MCS 
or remote file. 


Security 


COMS allows you to define security measures for direct windows through the COMS 
configuration file, through special processing items, and through direct-window 
programs. 


COMS directly controls access to various parts of the network (for example, to MCS 
windows and declared remote-file windows) through the use of authorized usercodes and 
authorized stations. These options are discussed in the COMS Configuration Guide. 


COMS also controls access through user-written processing items that perform security 
checking on usercodes and station names. See Section 5, “Processing Items,” for more 
information. 


In addition, you can write application programs that control security, based on 
information obtained from the COMS configuration file. For a complete discussion 
of programmatic control of the security of your COMS application in a direct-window 
program, refer to Section 8, “Security.” 


COMS controls access to MCS windows and declared remote-file windows through the 
use of authorized usercodes and authorized stations. 


Statistics Window 


Once you have installed your COMS direct-window environment, you can monitor 
system performance using the COMS Statistics window. COMS allows you to gather 
statistical summaries in the form of up-to-the-moment, online reports or in the form of 
much more extensive printed reports. See Section 4, “Accessing Service Functions,” for 
more information. 


' Database Recovery 


The database recovery feature (available for direct windows only, and only in the 
full-featured version) allows COMS to automatically resubmit transactions to your 
DMSIJI or SIM database after a transaction-state abort, system crash, or rollback. 
Recovery is performed for both interactive and batch updates. In addition, if you have 
implemented the protected input queue feature, recovery also causes messages in 


_ database program queues to be recovered and processed. 
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For information on writing a direct-window program that creates transaction trails, 
refer to Section 6, “Interactive Recovery.” For information on protected input queues 
and on identifying the DMSII databases to COMS, refer to the COMS Configuration 
Guide. For information on controlling transaction trails for a DMSII database, refer to 
the DATABASE command description in the COMS Operations Guide. For information 
on SIM, see the A Series InfoExec Semantic Information Management (SIM) Technical 
Overview. 
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Section 2 
Creating Your COMS Application 


To create a COMS application in a direct window or convert an application to the COMS 
environment, you must . 


e Write any processing items that are needed. 


e Write the direct-window programs. 


e Modify the configuration file to define a direct window, and link to it the programs 
and processing items for which it is intended. 


Suppose you wish to create a simple echo program to be run through a COMS direct 
window and to supply that program with one processing item that audits the messages 
and returns a duplicate of each message to the initiating station. To carry out this 
intention, you must do the following: 


1. Decide on a processing-item library convention and write the processing item to 
audit the message before coming to the direct-window program. Refer to Section 5, 
“Processing Items,” for information on doing these tasks. 


2. Write the direct-window program that receives and sends the messages. Refer to 
Section 3, “Communicating with COMS through Direct Windows,” for information 
about writing direct-window programs. 


3. Use the COMS Utility to modify the configuration file as follows: 


a. 
b. 


Cc. 


Define the processing-item library. 

Define the direct-window program. 

Name and define the characteristics of the direct window. 

Define the processing item and include that processing in a processing-item list. 


Define the agenda and include the window name, processing-item list name, and 
the direct-window program. 


Running an Application 


When you submit the command ON <your window name>, COMS will start your 
program. When the program executes a RECEIVE statement and COMS has a message 
for it, COMS constructs the input header, applies the specified agenda, and then exits. 


When your program sends a message, COMS applies the specified agenda (if any), routes 
the message, and then exits. 


Closing your window does not cause COMS to terminate your program; you must disable 
the program or the window. 
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Some Useful COMS Commands 


The following commands are useful for sending and receiving messages: 


e DISABLE PROGRAM < program name> 


COMS submits a null message to the program with a value of 99 in the Status Value 
field. For this command to work, the program must receive the message, and it 
must go to end of task (EOT) whenever it detects a Status Value message of 99. A 
disabled program cannot be started up, and messages for it are rejected. 


e DISABLE WINDOW < window name> 


COMS sends messages with a value of 99 in the Status Value field to all programs 
running in this window. The programs are not themselves disabled. 


e ENABLE PROGRAM <program name>/WINDOW < window name> 


The program or programs defined in the window can be started up to receive 
messages. Note that there is no enable library command. Libraries are started 
again as soon as a linkage is requested. 


Accessing Applications 


As a COMS user, you can choose to access applications in any of the following ways: 


e Through an existing message control system (MCS) window 
e Asremote-file programs 


e By writing new programs or converting existing applications for use in a 
direct-window environment 


MCS Window Applications 


Any of your applications that currently run in CANDE can be initiated from the CANDE 
window or from the MARC window. You can also run these CANDE applications as 
COMS-declared remote-file programs. In addition, you can define customized CANDE 
windows with some characteristics tailored to the programs you plan to run in those 
windows. See the COMS Configuration Guide for more information on defining new 
windows. Refer also to the A Series CANDE Configuration Reference Manual and the 
A Series Menu-Assisted Resource Control (MARC) Operations Guide for information 
about initiating programs in a CANDE or a MARC environment. 


For information about running GEMCOS applications through the GEMCOS window 


or installing your own MCS in the MCS window, refer to the A Series Communications 
Management System (COMS) Migration Guide. 


Remote-File Programs 


If you have existing programs that use the GEMCOS (or some other) remote-file 
interface, or if you have applications that can only receive input from one station per 
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copy of the program, you can run these programs in COMS remote-file windows. For 
information about running remote-file programs in the COMS environment, refer to 
Section 9, “Communicating with COMS through Remote-File Windows.” 


Direct-Window Applications 


To take advantage of COMS flexibility, you can convert your existing applications to a 
COMS environment or develop new applications for use in the COMS environment. 


To create a COMS direct-window application or to convert an application to run ina 
COMS direct-window environment, you need to make a number of decisions relating to 
the following issues: 

e Processing items 

e Your security scheme 

e Trancode routing | 

e Synchronized recovery 

e Program use of COMS features 

e Modifications to the COMS configuration file 


Processing Items 
Some decisions you should make about processing items are 
e What processing items, if any, should be written for your COMS applications in 
general? 
e What processing items are needed for the application you are designing? 
e Howshould these processing items be linked together in agendas? 
e What processing-item library convention should be used? 
Refer to Section 5, “Processing Items,” for information about programming a processing 


item. Refer to the COMS Configuration Guide for information about defining processing 
items in the configuration file. 


Your Security Scheme 
When planning your security scheme, consider the following questions: 


e What combination of COMS and application-based security measures will you use? 


e Ifyou do use COMS security, what features (including control of station access, 
program access, and usercode access to windows, trancodes, and stations) are 
appropriate for your needs? (Remember that trancode security measures are 
available only with full-featured COMS.) 


e Ifyou control station access, what trancodes will be permitted from a given window? 
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If you control program access, what trancodes will be embedded in the output 
messages of a given program? 


If you control access of usercodes, what stations and windows can a given usercode 
be logged on to, and what trancodes can that usercode use? 


To what stations, if any, do you wish to assign the continuous log-on capability? 


If COMS security features do not fill all your security needs, then what processing - 
items or security routines in your direct-window programs can add needed security - 
to your COMS applications? 


Refer to Section 8, “Security,” for information on programming for security, and to the 
COMS Configuration Guide for more information on the configuration file security 
measures. 


Trancode Routing 


If you are considering using trancode routing, some basic questions that need to be 
answered are 


Where in the message will you place the trancode? 


Will you be using the module function index (MFT) feature in your direct-window 
programs? 


What trancodes will you use? 

What security categories will you apply to the trancodes? . 
What trancodes will you allow to be used by what usercodes? 
What agenda routing do you plan for each trancode? 


See Section 8, “Communicating with COMS through Direct Windows,” for more 
information about programming for trancodes. For additional information on trancodes 
and security categories, refer to the COMS Configuration Guide. 


( 


Database Recovery 
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The following questions should be asked if you have full-featured COMS and will oe 
updating DMSII databases: 


@ 


Do you plan to use synchronized recovery? 
Do you plan to use protected input queues? 
Are you presently using the DMSII single-abort feature? 


Do your programs use concurrency control? 


If you are updating SIM databases, the following questions should be asked: 


Do you plan to use protected input queues? 


Do you plan to use archival recovery? 
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Refer to Section 6, “Interactive Recovery,” and to the COMS Operations Guide for 
details of synchronized recovery. 


Program Use of COMS Features 


Consider the following questions as you are planning how to create new direct-window 
applications or convert existing applications: 


Does the program have message areas to receive and send messages? 


How will the program be initialized? 


Refer to Section 3, “Communicating with COMS through Direct Windows,” for 
information about writing direct-window programs. 


Modifying the COMS Configuration File 


The following questions are important in determining how to change the COMS 
configuration file: 


What processing items need to be defined to COMS? 

How are they to be combined into agendas? 

What windows need to be defined? 

What agendas will be associated with what windows? 

What trancodes need to be defined? 

What programs need to be defined to COMS? 

What access will you allow to windows, trancodes, and stations? 
What stations, usercodes, and programs will be given access? 
What databases need to be defined? 


These questions are only a sample of the decisions that need to be made. For more 
information about modifying the COMS configuration file, refer to the COMS 
Configuration Guide. 
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section 3 | 
Communicating with COMS through 
Direct Windows 


When you use the direct-window interface of COMS, you have access to all the COMS 
features and functions, including the following: 


e Service functions that let you translate names into designator values and designator 
values into names to manipulate the entities of the COMS environment 
e Security checking of messages that programs receive and send 


e Processing items that can process message data before and after programs receive 
and send it 


e Dynamic opening of direct windows to terminals and dynamic communication over a 
modem 


If you are using the full-featured version of COMS, you also have access to the following 
features: 

e Message routing by transaction codes (trancodes) 

e Synchronized recovery for multiple database-processing programs that are running 


asynchronously 


This section presents each of the programming tasks necessary for communicating with 
COMS through direct windows and discusses the following topics: 

e Preparing a message area 

e Initializing a program 

e Creating a designator table 

e Programming to receive messages 

e Programming to send messages 

e Dynamically attaching to and detaching from stations 

The following program example provides the program flow for a direct-window program 
that does not interact with a database, and shows in pseudolanguage the necessary 


programming steps discussed throughout this section. Indentation is used in the 
pseudolanguage to indicate the scope of each statement. 
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KREKRKEKERREKERREREKE 


* DECLARATION PART * 


KEEKKKREREKRERKREKKKEKE 


COMS HEADER CDIN; 
COMS HEADER CDOUT; 
_ DATA AREA MSG; 


KREEKKEKEKKERERERERERKER 


* PROGRAM STRUCTURE * 


KKEKKKKEKKEKEKREKREREEE 


INITIALIZE_COMS; 
WHILE CDIN.STATUS NOT = 99 DO 
RECEIVE CDIN INTO MSG; 
IF CDIN.STATUS NOT = 99 THEN 
HANDLE_MSG; 
SEND CDOUT FROM MSG; 
— EXIT_COMS; 


KEKEKKRKEEERERREREEERE 


* INITIALIZE _COMS * 


KREKKKKEEERKRERERERE 


%Set up library title for COMS; Call to enable input% 


ESTABLISH _COMS_ LINK; 
ENABLE INPUT COMS "ONLINE"; 


KEKEKEEKKEKEEKKEE 


* EXIT_COMS * 


KRREREEKKRKREEKEER 


%No handling required% 


EXIT PROGRAM; 


Preparing a Message Area 


To receive and send messages, you must define a message area in which your program 
can build messages. You need to define the message area with a size and format 
appropriate to the data your program sends or receives. If a message area is too small to 
contain all the text for a message being sent or received, COMS truncates the message. 


COMS uses input and output headers to control the routing and description of your 


message. The available fields of these headers are presented later in this section in 
“Programming to Receive Messages” and “Programming to Send Messages.” 
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In a program that performs updates with Screen Design Facility (SDF) forms, the 
message area can receive the SDF form if you take the following steps: 


1. Define matching offsets for the message area and the SDF form. (The SDF form 
that you define with the SDF system must be at the same offset.) 


2. Name the SDF form instead of the message area record when using statements that 
receive or send a message. ; 


For examples of message areas declared in your programming language, refer to the 
appropriate language manual. 


Initializing a Program 


After you have prepared your message area, the next step required to prepare a 
program to send and receive messages is to provide for program initialization. 


To initialize your application program, you must do the following: 


1. Link to COMS. 


2. Provide for initializing the COMS interface, either in interactive or batch mode. 


For the specific program statements in your programming language, see the section on 
COMS program initialization in the appropriate language manual. 


Creating a Designator Table 


Often a program needs the designators that are associated with elements of the 
configuration file, such as agendas, data communication devices, programs, security 
categories, or usercodes. For this reason, you might want to include a table of element 
names and corresponding designators in your program. By using a table of this sort, 
your program can avoid making a call on COMS on each input for the designators the 
program needs. Each entity in the configuration file has a designator that can be used 
to reference the entity. This designator remains the same throughout an execution. If 
however, you do a dump and load of the configuration file, the designators will change. 


Because the layout of COMS designators may change with each software release, a 
program should never preserve any designator across executions. Do not, for example, 
use designators as keydata in a database, except in a restart data set. 


To create a designator table, do the following: 
1. Passa name to get a designator by using the appropriate COMS service function. 


Refer to Section 4, “Accessing Service Functions,” for additional information on 
COMS service functions. 


2. Create a table of configuration file element names and corresponding designators. 
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Programming to Receive Messages 


The following paragraphs provide information about receiving messages, as well as 
instructions for determining the message origin from fields in the input header. 


Using the Input Header 


If you want your program to receive a message from COMS, you must use an input 
header. A header (or message header), which is a sequence of characters separated from 
the data message itself, provides routing and descriptive information for a message. The 
header is an enhanced version of the communication descriptor that was used in the 
previous releases of COMS. The input header can be accessed both in processing items 
and in direct-window programs. 


Caution 


When you set up the receive area of your message header, include enough space 


for the characters of the message and all associated trancodes. If you do not allow 
adequate space, the message will be truncated. 


Depending on the language in which you are programming, the header name can either 
be defined by COMS or be a variable name that you choose. For specific information 
on using your programming language to define a header, see the appropriate language 
manual. 


Input Header Fields 


3-4 


COMS places values into the input header fields when a direct-window program executes 
a program statement that receives or accepts a message or that enables input to a 
terminal. The values describe the status of, and the circumstances encountered by, each 
message received by the program. Exceptions to this rule are as follows: 


e Ifyour program is updating a Data Management System II (DMSID) database, 
COMS places a designator representing the last audited message into the Restart 
field when the program executes a BEGIN-TRANSACTION with <text> statement 
or a MID-TRANSACTION statement. 


e COMS passes to the receiving program any data that a processing item has placed 
in the Conversation Area field of the input header. For information on processing 
items, see Section 5, “Processing Items.” 


The values COMS places into the input header fields are designators or integers that are 
part of an internal code understood by COMS and used in the COMS table structure. 
For most of the designators placed in the input header, you can use a service function of 
the COMS library to translate the designator to a name representing a COMS entity. 
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Service functions also allow you to translate names representing COMS entities to 
designators you use in output headers. 


The following is a list of input header fields and a description of their contents. To see 
the layout of COMS headers, see Appendix B. 


Program Designator Field 
This field can contain the following designators: 


e When a program or terminal is enabled, this field contains the program designator 
that COMS assigns to the program. COMS uses this information for database 
recovery operations. For more information on database recovery, see Section 6, 
“Interactive Recovery.” 


e When a message is received, this field contains the program designator of the 
program that originated the incoming message. If a station originated the message, 
this field contains a 0 (zero). 


Function Index Field 


This field contains a user-defined positive module function index (MFT) value that can be 
used for routing by trancode and security checking. 


A mnemonic is provided in Pascal and RPG for a Function Index field value of 0 (zero). 
See Table A~1 in Appendix A for a list of these mnemonics. 

Function Status Field 
This field can contain one of the following values: 


e ACOMS-defined error value 
e Values that report on the status of a dynamic attachment to another terminal 
e Values that are results of delivery confirmation requests for output messages 


e Values that are COMS notifications to direct windows of on/open activity, closure of 
the window, or a break condition in output from the window 


e Values that indicate the specific reason COMS has told a program to terminate 


For information on the meaning of specific values or mnemonics in the Function Status 
field, see Appendix A. 


Usercode Designator Field 


This field contains a designator representing the usercode associated with the program 
or station that originated the message. 
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Security Designator Field 


This field contains a session security designator. 


VT Flag Field 


This field is returned by COMS on input after the program has set the VT flag on 
output. The VT flag should be used only within a CP 2000 environment. See “Setting 
the VT Flag” later in this section for more information. 


Transparent Field 


This field indicates whether the input message is being passed in transparent mode (that — 
is, with no data formatting or translation). 


_ Timestamp Field 


This field contains the time and date (in the TIME(6) system format) that a message was 
first encountered by COMS. COMS audits the transaction trail for the time and date 
appearing in this field when the program executes a MID-TRANSACTION statement. 


Station Designator Field 
This field can contain the following designators: 
e Ifa program receives a message, this field contains a designator representing the 
station that originated the incoming message. . 


e Ifa program originated the message, this field contains the station designator found 
in the Station Designator field of the input header of the originating program. 


e Ifa program dynamically attaches or detaches a terminal, the station designator in 
the Station Designator field represents the attached or detached terminal. 


Text Length Field 
This field can contain the following values: 
e When a program receives a message, this field contains the number of characters in 
the text of the incoming message. 


e When the program enables an input terminal with the DIAL option, this field 
contains the length of the phone number of the destination. 


e When a program requests delivery confirmation on output, this field contains the 
length of the delivery confirmation result returned by COMS on input. 


e This field contains a value of 0 (zero) when COMS notifies a direct window of — 
on/open activity with no text, closure of a window, or a break in output from the 
window. 
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Status Value Field 
This field contains a numeric value that provides the following information: 


e Confirmation as to whether an output message successfully reached its destination 
e Identification of a synchronized recovery message 
e Status of a message after it is processed by a processing item 


e Indication that a program dynamically attached or detached a terminal, or was 
unable to do so 


e Indication that a program was asked to terminate 
For information on the meanings of the values and associated mnemonics in this field, 
see Appendix A. 

Message Count Field 


When a program executes a statement to determine whether messages from COMS are 
waiting in the queue of the program, this field contains the number of queued messages. 


Restart Field 
When a direct-window program enters the transaction state while updating a DMSII 
database for a previous release, this field contains a designator representing the last 
message that COMS audited in the transaction trail. The Pascal programming language 
does not support a COMS DMSII interface and therefore does not use this field. 
Agenda Designator Field 


When a program receives a message, this field contains the designator of the most 
recently applied input agenda. 


When you use a processing item to call OUTPUT_PROC with an input header and you 
want to specify an agenda, the agenda designator must be placed in this field. 


SDF Information Field 


COMS uses this field internally. 
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Conversation Area Field 


This field is optional and is the only user-defined field in the header. For the correct 
syntax to use when defining the field, see the appropriate language manual. This field 
can contain the following information: . 


e Information passed by a program to processing items, by processing items to other 
processing items, and by processing items to a program. 


e The phone number of the destination, if a direct-window program enables an input 
terminal with the DIAL option. 


e Information that a program puts in the transaction trail for its own DMSII or SIM 
recovery purposes. Recovery data is passed back to the application program when 
transactions are resubmitted by COMS. Recovery data is unique to a particular 
transaction and must not be used to retain information between transactions, such 
as storing running totals in a program. 


Detecting Queued Messages 


You can use a statement in your program to determine whether messages from COMS 
are waiting in the queue of the program. See the appropriate language manual for this 
program statement. If messages are queued, the program can perform a routine that 
receives messages from COMS. If the program queue does not contain any messages 
from COMS, the program can perform a routine that processes messages from other 
sources. . 


When a program executes the statement, COMS places the number of queued messages 
in the Message Count field of the input header. If more than one copy of your program is 
running, the value obtained by executing the statement is the sum of messages queued 
for all the copies. Since your program might not be able to receive all the queued 
messages reported by the statement, you must not use the Message Count field as a loop 
controller. 


After executing the statement, the program queries the Status Value field of the input 
header. Table 3-1 shows the four possible values the field can contain. 


Table 3-1. Possible Values for the Input Header Status Value Field 


Value - Description 


The Message Count field contains the number of messages 
queued for the program. 


This value indicates that COMS is currently performing a 
synchronized recovery on a DMSII database. The program 
executes the RECEIVE statement to handle the recovery 
transactions. 


continued 
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Table 3-1. Possible Values for the Input Header Status Value Field (cont.) 


Value Description 


The program has aborted and then restarted. The Message 
Count field contains a nonzero value. This value does not 
indicate the total number of messages queued for the 
program. The program should execute RECEIVE statements 
to handle the recovery. 


The program will be directed to terminate, but it should 
execute a RECEIVE statement to get its transactions and its 
status 99 message. 


For mnemonics associated with these values, see Appendix A in this guide. 


In some programming languages, the program does not need to query the Status Value 
field. The call itself returns the value. See the appropriate language manual for further 
information. 


Waiting for COMS Input and Task Events 


COMS provides a library entry point, the DCIWAITENTRYPOINT, that programs can 
call when waiting for an event to happen. Event-driven ALGOL programs can wait for 
two COMS events. In some cases, the nature of the transaction-processing program 

is such that it requires more awareness of external events than those handled by the 
COMS DCT interface. In these cases, in ALGOL, a program can wait for other time 
periods and required events in addition to the COMS events. 


For a given transaction processor (TP), COMS causes either an input event or a task 
event to happen. One input event is shared among all copies of a program. The input 
event remains set to HAPPENED if messages are in the input queue of the program. 
All copies of the program waiting for the input event are awakened. On the other hand, 
each copy of a program has its own task event. COMS causes the task event to happen 
for a specific copy of a program when COMS wants to perform a task-specific function, 
such as giving a copy instructions to go to end of task (EOT) or to process a message 
during recovery. 


TPs must not reset either of these events. COMS causes the event to happen at the 
appropriate time and resets the event when it is no longer needed. 
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The program must declare a real value procedure that contains the statement with the 
WAIT option set. The procedure must also take the two events as formal parameters, 
and other events and variables must be visible to this procedure. The following 

is an example of a real value procedure that contains the value returned by the 


DCIWAITENTRYPOINT function: 


REAL PROCEDURE DCIWAITENTRYPOINT ( WAIT PROC ) 


REAL PROCEDURE WAIT_PROC ( COMS_INPUT_EVENT , 
COMS_TASK_EVENT ) ; 


EVENT 
COMS_INPUT_EVENT , 
COMS_TASK_EVENT ; 

FORMAL 3; 
LIBRARY COMS DCI_LIBRARY ; 


INTEGER 
MY TIMEOUT ; 

FILE 
MY_REMOTE_FILE ( KIND = REMOTE) , 
MY PORT FILE ( KIND = PORT ) ; 


EVENT 
MY_COROUTINE_EVENT 3; 


REAL PROCEDURE MY_WAIT ( COMS_INPUT_EVENT , . 
COMS_TASK_EVENT ) ; 
EVENT 
COMS_INPUT_EVENT , 
COMS_TASK_EVENT ; 
BEGIN 
MY_WAIT := WAIT ( ( MY_TIMEOUT ) , 
COMS_INPUT_EVENT , 
COMS_TASK_EVENT , 


MY REMOTE_FILE.INPUTEVENT , 


MY_PORT_FILE.INPUTEVENT , 
MY PORT FILE.CHANGEEVENT , 
MY COROUTINE EVENT ) ; 

END MY_WAIT ; 


CASE DCIWAITENTRYPOINT ( MY_WAIT ) OF 
BEGIN 
3; % NEVER RETURNS (8). 
HANDLE_TIMEOUT ; 
HANDLE_COMS_ INPUT : 
HANDLE_COMS_TASK 3; 
HANDLE-REMOTE_FILE_INPUT ; 
HANDLE_PORT_FILE_INPUT ; 
HANDLE_PORT_FILE_CHANGE 3; 
HANDLE _COROUTINE_EVENT ; 
END ; . 
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If the DCIWAITENTRYPOINT result indicates that either a COMS input is present or a 
COMS task event has happened, the program performs a conditional COMS RECEIVE 
function (that is, a RECEIVE statement with the DONTWAIT option set). 


More than one copy of a program might be running at the same time. Every copy of 
a program that has called the DCIWAITENTRYPOINT function is awakened by the 
triggering of the input event, but only one copy receives the message that caused the 
event to be triggered. Asa result, all other copies could wait indefinitely for the next 
transaction if they request a COMS RECEIVE function with the WAIT option set. 


The DCIWAITENTRYPOINT function can be used only by ALGOL programs because 
all other programming languages do not allow procedures to take events as formal 
parameters when calling a subroutine. 


Receiving a Message 


A RECEIVE statement in your program informs COMS that you are ready to process a | 
message. COMS, in turn, sends the message to your message area. 


You can use a RECEIVE statement as many times as needed in your program. You can 

structure your program to receive messages from one or more stations or programs, but 
you cannot programmatically limit the reception of messages to selected stations on the 
network or to certain types of programs. 


The syntax for the use of the RECEIVE statement depends upon the programming 
language you are using. See the appropriate language manual for further information on 
using the RECEIVE statement in your program. 


Determining the Origin of a Message - 


To determine the origin of a message, check the Program Designator field and the 
Station Designator field in the input header. In addition, check the Status Value field 
of the input header to determine the message status. You are not required to know the 
origin of a message, but it is strongly recommended to check the message status. 


Refer to “Using the Input Header” in this section for additional information on the input 
header. 


To determine a message origin from the input header, use the following procedure: 


1. Check the Program Designator field. When a program executes a RECEIVE 
statement, the Program Designator field of the input header contains one of the 
following: 


e Adesignator representing the program that originated the message 


e The value 0 (zero) or a null-designator to indicate that the message came from a 
station 


If this field contains a value of 0 (zero), you must check the Station Designator field 
for the originating station. = 
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2. Check the Station Designator field. When a program executes a RECEIVE 
statement and a station originated the message, the Station Designator field of the 
input header contains a designator representing the station that originated the 
message. 


If a program originated the message, this field contains the station designator found 
in the Station Designator field of the input header of the originating program. 


Using Module Function Indexes with Input 


To facilitate the processing of messages using the transaction code routing method, you 
can associate a module function index (MFI) with each trancode or group of trancodes. 
This association is made in the configuration file. For instructions on using the COMS 
Utility to assign these MFIs, refer to the COMS Configuration Guide. 


Once these MFIs are defined, any time a program executes a RECEIVE statement, 

the Function Index field of the input header contains the MFI assigned to the trancode 
associated with the incoming message, unless the message came from another program. 
The MFI can be used for routing messages to particular transaction-processing routines 
within a program, assuming that the value of the MFI can be matched to a routine ina 
program. 


COMS checks the validity of the trancode before reaching your program. If the trancode 
is invalid, COMS applies the default input agenda to the message. If no default input 
agenda has been defined, COMS rejects the message and the station receives an error 
message. The Function Status field and the Status Value field of the input header should 
be checked for error messages. Refer to Appendix A for the possible error values that 
COMS returns. 


Obtaining Direct-Window Notifications 
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COMS automatically returns values to certain input header fields of direct-window 
programs through the default input agenda when a ?ON <window name> or ?CLOSE 
<window name> command is issued to the direct window, or when a break in output 
from the direct window is detected. These values appear in the input header the next 
time the destination program of the default input seca receives a message with a 
RECEIVE statement. 


When you define a direct window with the COMS Utility program, you can specify Open 
Notification and On Notification text that the window receives for an initial opening 

and for every subsequent opening. If you do not provide any text for On and Open 
Notification (blanks are the default value), the Text Length field of the input header 
contains a value of 0 (zero). For information on values that appear in the Function 
Status field when you do not provide any text for On and Open Notification, see 
Appendix A. 


When a break condition causes output from a direct window to be discarded, COMS 
reports this to the direct window by routing an input to the default input agenda of the 
direct window and by placing a value of 0 (zero) in the Text Length field of the input 
header. See Appendix A for values placed in the Function Status field. 
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The break notification is the only message that will inform the program that messages 
were discarded. Even if delivery confirmation has been requested on any of the 
discarded messages, a delivery confirmation rejection message is not sent with that 
message. 


When you close a direct window with the ?CLOSE <window name> command, COMS 
reports the closure by routing an input to the default input agenda of the direct window 
and by placing a value of 0 (zero) in the Text Length field of the input header. See 
Appendix A for values placed in the Function Status field. 


Manipulating Closed Window Dialogues 


After you close a window dialogue, any message sent to that dialogue is discarded. You 
are then assigned another current window based on the type of window you are closing 
and how the window is defined in the configuration file, as follows: 


e Ifthe window you are closing is a dynamic remote-file window, you are assigned to 
the dialogue of the MARC window from which the dynamic remote-file window was 
initiated. 


e Ifthe window you are closing is a direct window (defined in the configuration file), an 
MCS window, or a declared remote-file window, then the action COMS takes when 
closing the window is determined by the configuration file. You can specify which 
window you want to be transferred to when your current window closes. The close 
action value that is specified for your station or your usercode in the configuration 
file determines the action that is taken. Refer to the COMS Configuration Guide for 
information on possible close actions. 


Checking the Status of Input Messages 


You can determine the status of an input message by checking the Status Value field in 
the input header. When a RECEIVE statement is executed, a value is returned in the 
Status Value field to indicate the status of a message. When the Status Value is 99, the 
program should perform its end routines and go to end of task (KOT). 


The meanings of the values are described in Appendix A. 
Note: Future releases of COMS might add values to the Status Value field 


of the input header. You need to keep this in mind when writing a 
program that makes use of the values this field can contain. 


Programming to Send Messages 


You can use a SEND statement in your program to send messages to stations or to other 


programs, although you can send a message to only one destination with each SEND 
statement. 


You can send a message to multiple stations or programs in two ways. The first method 


uses multiple send commands; each one specifies a different destination. The second 
method uses an agenda that includes a processing item that calls the OUTPUT_PROC 
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procedure to send the message to multiple destinations. Refer to “OUTPUT PROC 
Parameter” in Section 5, “Processing Items,” for additional information about the 
OUTPUT PROC procedure. 


If you plan to have your program send a message using COMS, you must use an output 
header. The following pages describe the output header and its fields. 


Using the Output Header 


A header, or message header, is a sequence of characters, separated from the data 
message itself, that provides routing or descriptive information for a message. 


Depending on the language in which you are programming, the header name can either 
be defined by COMS or be a variable name that you choose. For specific information 
on using your programming language to define a header, see the appropriate language 
manual. 


Output Header Fields 


Place designators into the output header fields to route outgoing messages and describe 
their characteristics. You can obtain designators by calling service functions of the 
COMS library. If an error occurs when a program sends an outgoing message, COMS 
returns an error value to the Status Value field described later in this section. For the 
layout of COMS headers, see Appendix B. 


Destination Count Field 


This integer field specifies the number of destinations to which the program can send a 
message. COMS supports only one destination. 


Text Length Field 


Use this field to specify the number of characters contained in the text of an outgoing 
message; it is the only way to inform COMS about the length of your message. 


Status Value Field 
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With this field you can specify an agenda designator for postprocessing of the message 
that a program is sending. It is recommended that you use the Agenda Designator field 
for this purpose. If your window has a default output agenda, you do not need to oo 
an agenda for postprocessing. 


After the program sends a message, COMS returns an integer value to this field to 
indicate whether the message was successfully sent to its destination or if an error 
occurred. 


For information on specific values and mnemonics, see Appendix A. 
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Carriage Control Field 
This field can be accessed either by a processing item or a program. A program can 
modify this field either directly or by means of an explicit carriage-control specification 
in the SEND statement. If there is no carriage-control specification in the SEND 
statement, COMS does not alter the value that might have been entered directly into 
this field. 
A processing item can modify this field to change the carriage control specification for an 
output message that was initially provided by a program either directly or in its SEND 
statement. | 


Delivery Confirmation Flag Field 


Use this field to request delivery confirmation of an output message. 


Delivery Confirmation Key Field 
This field is used by a program requesting delivery confirmation to uniquely identify each 
message. When COMS subsequently confirms or denies delivery, this identifying value is 


returned as part of the confirmation message. See “Requesting Delivery Confirmation” 
in this section for more information on confirming delivery of a message. 


VT Flag Field 
Use this field to set the virtual terminal flag on an output message to a CP 2000 station. 
See “Setting the VT Flag” later in this section for more information. 

Transparent Field 
Use this field to specify transparent mode for an output message to a CP 2000 station. 
Transparent mode is an operating mode in which there is no data formatting or 
translation. 


Destination Designator Field 


This field specifies an optional destination for a message. 


Next Input Agenda Designator Field — 


If the Set Next Input Agenda field is equal to 1 (TRUE), this field specifies the agenda 
that is to be applied to the next input to the current dialogue of the destination station. 
For information on specifying the next input agenda, see “Program-Specified Input 
Agendas” in this section. 
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Set Next Input Agenda Field 


This field specifies whether COMS is to use the contents of the Next Input Agenda 
Designator field to change the agenda for the next input to the current dialogue of 
the destination station. For information on specifying the next input agenda, see 
“Program-Specified Input Agendas” in this section. 


Retain Transaction Mode Field 


This field specifies whether transaction mode is to be retained for the current dialogue. 
A value of 1 (TRUE) indicates that transaction mode is not to be cleared for the dialogue 
when the output is delivered. A value of 0 (FALSE) indicates that transaction mode is 
to be cleared. For information on the use of transaction mode, see “Using Agendas for 
Message Routing” in this section. 


Casual Output F ield 


Use this field to produce casual output for a protected transaction whose output is 
protected by default. Enter J in this field to produce casual output. If you enter 0, the 
type of output produced depends on whether or not the transaction is protected. (If the 
transaction is protected, the output is protected.) COMS does not change the value of 
the field once it has been enabled. Therefore, be sure to change the value back to 0 if 
you are using the same COMS output header with subsequent output messages that you 
want protected. 


Casual output is any output that is not protected. Casual output is delivered 
immediately except for delays when output tanking is necessary; the casual output can 
be lost if delivery is interrupted by a system failure. All COMS output for transaction 
that are not protected is casual output. 

Agenda Designator Field 
With this field you can specify an agenda for postprocessing of the message that a 
program is sending. The Status Value field can still be used for this purpose, but use of 
the Agenda Designator field is recommended. 
If processing items do not change the contents of the Agenda Designator field, it does 


not need to be reloaded every time the program sends a new message. The Status Value 
field does not offer this feature. 


SDF Information Field 


This field is used internally by COMS. 


Conversation Area Field 


This field is optional and is the only user-defined field in the header. For the correct 
syntax to use when defining the field, see the appropriate language manual. 
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Use this field to pass information (in addition to the message data) to processing items. 
For example, to use an SDF form with a COMS direct-window program, aaa a form key 
in the first word of the Conversation Area field. 


Declaring Multiple Input and Output Headers 


You can declare multiple input and output headers in your program to move messages in 
and out of different processing states. By declaring multiple headers, you can maintain 
the flow of incoming and outgoing messages. 


The following two examples illustrate the flow of programs that use multiple headers. 
The first example contains one input header and two output headers. The second 
example contains multiple input and output headers. 


Example 1 


BOB40G 
GB9500 
GOGbOS 
9BB7 OB 
QOG8G0 
B2B9IBO 
021900 
9B1198 
GB128D 
981398 
GB1400 
881588 
981682 
881789 
GB1880 
201989 
BB2980 
982180 
GB2208 
982300 
BB2408 
202588 
892629 
962726 
902880 
BB2988 
993809 
903160 
883280 
983300 
983408 
963508 
903626 
903780 


IDENTIFICATION DIVISION. 


PROGRAM-ID. TEST-FILE. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. A-SERIES. 
OBJECT-COMPUTER. A-SERIES. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 

SELECT PRT-FILE ASSIGN TO PRINTER. 
DATA DIVISION. 
FILE SECTION. 
FD PRT-FILE. 


G1 


WORKING-STORAGE SECTION. 


G1 


G1 


G1 


G1 


PRINT-REC. 
@2 FILLER 


MY-AREA. 

2 JUNK-IN 
JUNK-1. 

G2 JUNK-2 
G2 JUNK-OUT 
WS-AREA. 

G2 FILLER 
G2 FILLER 
G2 WS-MSG1 
@2 FILLER 
G2 FILLER 
G2 WwS-MSG2 
92 FILLER 
2 FILLER 
G2 WS-MSG3 
G2 FILLER 
XYZ. 

G2 ALWAYS 
Q2 THETWO 


883896 COMMUNICATION SECTION. 
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PIC 


PIC 


PIC 
PIC 


PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 


PIC 
PIC 


X(132). 


X (28) .° 


9(5) USAGE BINARY. 
$9(11) USAGE BINARY. 


X (108) . 
X(2@) VALUE 
X (28) . 

X (4B). 

X(28) VALUE 
X (28) . 
X(49). 

X(2@) VALUE 
X (28) . 

X (1620) . 


"FIRST MESSAGE IS :". 
"SECOND MESSAGE IS :". 


"THIRD MESSAGE IS :". 


X (168) . 
X (1768) . 
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803989 INPUT HEADER COMS-IN 


@G489G PROGRAMDESG IS COMS-IN-PROGRAM 

@@419G FUNCTIONSTATUS IS COMS-IN-FUNCTION-STATUS 
OG4208 FUNCTIONINDEX IS COMS-IN-FUNCTION-INDEX 
684309 USERCODE IS COMS-IN-USERCODE 

884490 SECURITYDESG IS COMS-IN-SECURITY-DESG 
624506 TRANSPARENT IS COMS-IN-TRANSPARENT 

GB4600 VTIFLAG IS COMS-IN-VT-FLAG 

@G4706 TIMESTAMP IS COMS-IN-TIMESTAMP 

804886 STATION IS COMS-IN-STATION 

684989 TEXTLENGTH IS COMS-IN-TEXT-LENGTH 

885008 STATUSVALUE IS COMS-IN-STATUS-KEY 

825196 AGENDA IS COMS-IN-AGENDA 

@05296 SDFINFO IS COMS-IN-SDF-INFO. 

085300 OUTPUT HEADER COMS-OUT 

085480 DESTCOUNT IS COMS-OUT-COUNT 

065580 TEXTLENGTH IS COMS-OUT-TEXT-LENGTH 
Q256GB STATUSVALUE IS COMS-OUT-STATUS-KEY 

9625706 TRANSPARENT IS COMS-OUT-TRANSPARENT 
985880 VTFLAG IS COMS-OUT-VT-FLAG 

625996 CONFIRMFLAG © IS COMS-OUT-CONFIRM-FLAG 
826000 CONFIRMKEY IS COMS-OUT-CONFIRM-KEY 
886108 DESTINATIONDESG IS COMS-OUT-DESTINATION 
QB620B NEXTINPUTAGENDA IS COMS-OUT-NEXT-INPUT-AGENDA 
@86388 CASUALOUTPUT IS COMS-OUT-CASUAL-OUTPUT 
986400 SETNEXTINPUTAGENDA IS COMS-OUT-SET-NEXT-INPUT-AGENDA 
@@6586 RETAINTRANSACTIONMODE IS COMS-OUT-SAVE-TRANS-MODE 
8866089 AGENDA ITS COMS-OUT-AGENDA 

986708 SDFINFO IS COMS-OUT-SDF-INFO 

@@68G9 CONVERSATION AREA. : 
GB6900 @2 MSG-AREA PIC X(1929). 

827606 OUTPUT HEADER COMS-OUT1 

887186 DESTCOUNT . IS COMS-OUT-COUNT 

987286 TEXTLENGTH IS COMS-OUT-TEXT-LENGTH 
87398 STATUSVALUE IS COMS-OUT-STATUS-KEY 

927496 TRANSPARENT . IS COMS-OUT-TRANSPARENT 
987598 VTFLAG IS COMS-OUT-VT-FLAG 

927606 CONFIRMFLAG IS COMS-OUT-CONFIRM-FLAG 
0877086 CONFIRMKEY IS COMS-OUT-CONFIRM-KEY 
897889 DESTINATIONDESG IS COMS-OUT-DESTINATION 
627986 NEXTINPUTAGENDA IS COMS-OUT-NEXT-INPUT-AGENDA 
828089 CASUALOUTPUT IS COMS-OUT-CASUAL-OUTPUT 
988198 SETNEXTINPUTAGENDA IS COMS-OUT-SET-NEXT-INPUT-AGENDA 
998299 RETAINTRANSACTIONMODE IS COMS-OUT-SAVE-TRANS-MODE 
988306 AGENDA IS COMS-OUT-AGENDA 

988406 SDFINFO IS COMS-OUT-SDF-INFO 

@28500 CONVERSATION AREA. 

GB8600 @2 MSG-AREA-1 PIC X(1929). 


88796 PROCEDURE DIVISION. 

898899 INITIAL-PARA. 

BB89GG CHANGE ATTRIBUTE LIBACCESS OF "DCILIBRARY" TO BYFUNCTION. 
G89GBOO CHANGE ATTRIBUTE FUNCTIONNAME OF "DCILIBRARY" TO 
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669186 "COMSSUPPORT". 

BB920B ENABLE INPUT COMS-IN KEY "ONLINE". 

0693080 HK-PARA. 

BOIABD MOVE "COMS" TO PRINT-REC. 

GB952G MOVE "IT IS OK" TO XYZ. 

GB962D RECEIVE COMS-IN MESSAGE INTO XYZ. 

8897 2B MOVE 1928 TO COMS-OUT-TEXT-LENGTH OF COMS-OUT1. 
BB98LG MOVE "HELLO YOU ARE IN. " TO ALWAYS. © 

9B99BB MOVE "PLEASE GIVE THREE MEANINGFUL MESSAGES." TO THETWO. 
G190829 SEND COMS-OUT1 FROM XYZ. 

G19109 RECEIVE COMS-IN MESSAGE INTO MY-AREA. 

19158 = MOVE JUNK-IN TO WS-MSG1. 

819209 MOVE 1928 TO COMS-OUT-TEXT-LENGTH OF COMS-OUT. 
019329 SEND COMS-OUT FROM JUNK~IN WITH ESI. 

819489 RECEIVE COMS-IN MESSAGE INTO MY-AREA. 

019459 MOVE JUNK-IN TO WS-MSG2.. 

019588 SEND COMS-OUT FROM JUNK-IN WITH ESI. 

G19600 RECEIVE COMS-IN MESSAGE INTO MY-AREA. 

618659 MOVE JUNK-IN TO WS-MSG3 

818729 SEND COMS-OUT FROM JUNK-IN WITH ESI. 

G10800 MOVE 1928 TO COMS-OUT-TEXT-LENGTH OF COMS-OUT. 
G19909 SEND COMS-OUT FROM WS-AREA WITH EGI AFTER ADVANCING 19 LINES. 
9110889 IF COMS-IN-STATUS-KEY = 99 GO TO EOJ. 

(811199 DISPLAY XYZ. 

811288 ACCEPT COMS-IN MESSAGE COUNT. 

811388 E0J. 

811489 STOP RUN. 


Example 2 


200100$ RESET FREE 

BOG15G******* $ SET LISTDOLLAR 

goo2B0******* $ SET LIST WARNSUPR 

@@03@0 IDENTIFICATION DIVISION. 

@Q040G PROGRAM-ID. GOOD-SYNTAX. 

200500* : 

@0060* ALL VALID SYNTAX PRODUCTIONS FOR COMS HEADERS. 
@00708* THERE SHOULD BE NO SYNTAX ERRORS. 

goo8en* 

@0090G ENVIRONMENT DIVISION. 

@@1@GG CONFIGURATION SECTION. 

@@1108 SOURCE-COMPUTER. A3. 

@01200 OBJECT-COMPUTER. A3. 

@01380* | 

221488 DATA DIVISION. 

901500* 

@G160@ COMMUNICATION SECTION. 

@G1708 INPUT HEADER IH1. | 

@G18GG INPUT HEADER IH2 PROGRAMDESG COMS-PROGRAMDESG. 
@0190@ INPUT HEADER IH3 PROGRAMDESG IS COMS-PROGRAMDESG. 
@02@0G INPUT HEADER IH4 CONVERSATION AREA CA SIZE 123. 
@02108 INPUT HEADER IH5 CONVERSATION AREA IS CA SIZE 123. 


8600 0650-000 . 3-19 


Communicating with COMS through Direct Windows 


3-20 


BB2208 
962308 
B62488 
BO258D 
802608 
862702 
GO2888 
882988 
GO3000 
883180 
883298 
983360 
983408 
983508 
963600 


INPUT 
INPUT 
INPUT 


INPUT 
INPUT 
INPUT 
INPUT 
INPUT 


INPUT 
INPUT 
INPUT 
INPUT 
INPUT 


HEADER 
HEADER 
HEADER 
G2 CA. 
HEADER 
HEADER 
HEADER 
HEADER 
HEADER 
G2 CA. 
HEADER 
HEADER 
HEADER 
HEADER 
HEADER 
62 CA. 


IH6 CONVERSATION AREA IS CA SIZE IS 123. 
IH7 CONVERSATION AREA. 82 CA PIC X(123). 
IH8 CONVERSATION AREA. 


@5 CAl PIC 
IH9 VTFLAG 
IHA VTFLAG 
IHB VTFLAG 
IHC VTFLAG 
IHD VTFLAG 
85 CAl PIC 
THE VTFLAG 
IHF VTFLAG 
IHG VTFLAG 
THH VTFLAG 
IHI VTFLAG 
@5 CAl PIC 


X. @5 CA2 PIC X. 
IS V CONVERSATION AREA CA SIZE 123. 
IS V CONVERSATION AREA IS CA SIZE 123. 


IS V CONVERSATION AREA IS CA SIZE IS 123. 
IS V CONVERSATION AREA. 22 CA PIC X(123). 


IS V CONVERSATION AREA. 

X. @5 CA2 PIC X. 

V CONVERSATION AREA CA SIZE 123. 

V CONVERSATION AREA IS CA SIZE 123. 

V CONVERSATION AREA IS CA SIZE IS 123. 
V CONVERSATION AREA. @2 CA PIC X(123). 
V CONVERSATION AREA. 

X. @5 CA2 PIC X. 


64188 OUTPUT 


903728 
G03800* 
@039G@ OUTPUT HEADER OH1. | 

@G4GBG OUTPUT HEADER OH2 AGENDA COMS-AGENDA. 

HEADER OH3 AGENDA IS COMS-AGENDA. 

@G42GG OUTPUT HEADER OH4 CONVERSATION AREA CA SIZE 123. 

@G43@B OUTPUT HEADER OH5 CONVERSATION AREA IS CA SIZE 123. 

@G44GG OUTPUT HEADER OH6 CONVERSATION AREA IS CA SIZE IS 123. 

@@45G0@ OUTPUT HEADER OH7 CONVERSATION AREA. @2 CA PIC X(123). 

@B46BG OUTPUT HEADER OH8 CONVERSATION AREA. 

@B4700 @2 CA. @5 CAl PIC X. @5 CA2 PIC X. 

@Z48GB OUTPUT HEADER OH9 VTFLAG IS V CONVERSATION AREA CA SIZE 123. 
@G49GS OUTPUT HEADER OHA VTFLAG IS V CONVERSATION AREA IS CA SIZE 123. 
@@5GGS OUTPUT HEADER OHB VTFLAG IS V CONVERSATION AREA IS CA SIZE IS 1. 
@@51@G OUTPUT HEADER OHC VTFLAG IS V CONVERSATION AREA. @2 CA PIC X(1). 
@@520G OUTPUT HEADER OHD VTFLAG IS V CONVERSATION AREA. 

205300 @2 CA. @5 CAl PIC X. G5 CA2 PIC X. 

@@54@G OUTPUT HEADER OHE VTFLAG V CONVERSATION AREA CA SIZE 123. 
@@55QB OUTPUT HEADER OHF VTFLAG V CONVERSATION AREA IS CA SIZE 123. 
@@56@G OUTPUT HEADER OHG VTFLAG V CONVERSATION AREA IS CA SIZE IS 123. 
@@570@ OUTPUT HEADER OHH VTFLAG V CONVERSATION AREA. @2 CA PIC X(123). 
@@580S OUTPUT HEADER OHI VTFLAG V CONVERSATION AREA. 


885909 92 CA. 95 CAl PIC X. 5 CA2 PIC X. 
BB6BBB* 

886108 PROCEDURE DIVISION. 

8B6200* 


$66398 MAIN-SECTION SECTION. 
696409 MAIN-PARA. 


986588 MOVE 1 TO AGENDA OF IH1. 

886680 MOVE 1 TO COMS-PROGRAMDESG OF IH2. 

886728 MOVE 1 TO COMS-PROGRAMDESG OF IH3. 

986800 MOVE "HI" TO CA OF IH4. 

BB698G MOVE "HI" TO CA OF IH5. 

967980 MOVE "HI" TO CA OF IH6. 

897198 MOVE "HI" TO CA OF IH7. 

967208 MOVE "H" TO CAl OF IH8. MOVE "I" TO CA2 OF IH8. 
887380 IF V OF IH9 NEXT SENTENCE. 
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987409 
987508 
987699 
907788 
987820 
887998 
QO8BBB 
988198 
GB8298 
G88390* 
968490 
98509 
908606 
988788 
G88890 
G08 98D 
GO9IGBLD 
989198 
969298 
969399 
989499 
989586 
989699 
9B979B 
GB98L6 
889980 
919990 
910190 
G18298 


Ht 
TN 
<< sce ccc =< 
oO 
nn 


MOVE 1 TO 
MOVE 1 TO 
MOVE 1 TO 
MOVE "HI" 
MOVE "HI" 
MOVE "HI" 
MOVE "HI" 


MOVE "H" TO 
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OF IHA NEXT 
OF IHB NEXT 
OF IHC NEXT 
OF IHD NEXT 
IHE NEXT 
OF IHF NEXT 
OF IHG NEXT 
OF IHH NEXT 
OF IHI NEXT 


AGENDA 


SENTENCE. 
SENTENCE. 
SENTENCE. 
SENTENCE. 
SENTENCE. 
SENTENCE. 
SENTENCE. 
SENTENCE. 
SENTENCE. 


OF OH1. 


MOVE 
MOVE 
MOVE 
MOVE 
MOVE 
MOVE 
MOVE 
MOVE 
MOVE 


COMS-AGENDA OF OH2. 
COMS-AGENDA OF OH3. 
TO CA OF OH4. 
TO CA OF OH5. 
TO CA OF OH6. 
TO CA OF OH7. 


IF V OF OH9 NEXT 


V OF OHA NEXT 
V OF OHB NEXT 
V OF OHC NEXT 
IF V OF OHD NEXT 
V OF OHE NEXT 
V OF OHF NEXT 
V OF OHG NEXT 
V OF OHH NEXT 


IF V OF OHI NEXT 


STOP RUN. 
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CAl OF OH8. MOVE "I" 
SENTENCE. 
SENTENCE. 
SENTENCE. 
SENTENCE. 
SENTENCE. 
SENTENCE. 
SENTENCE. 
SENTENCE. 
SENTENCE. 
SENTENCE. 


MOVE 
MOVE 
MOVE 
MOVE 
MOVE 
MOVE 
MOVE 
MOVE 
MOVE 


"HI" TO CA 
MHI? TOCA 
"HI" TO CA 
"H" TO CAl 
"HI" TO CA 
"HI" TO CA 
"HI" TO CA 
"HI" TO CA 
"H" TO CAl 


TO CA2 OF 


"HI" TO CA 
"HI" TO CA 
"HI" TO CA 
"H" TO CAl 
"HI" TO CA 
"HI" TO CA 
"HI" TO CA 
"HI" TO CA 
"H" TO CAl 


OF 
OF 
OF 
OF 
OF 
OF 
OF 
OF 
OF 


IHA. 
THB. 
IHC. 
IHD. 
THE. 
IHF. 
IHG. 
THH. 
IHI. 


OH8. 


OF 
OF 
OF 
OF 
OF 
OF 
OF 
OF 
OF 


OHA. 
OHB. 
OHC. 
OHD. 
OHE. 
OHF. 
OHG. 
OHH. 
OHI. 


When you use a SEND statement to send a message, the message is routed by COMS 
based on the presence and validity of the following items: 


e Adestination, as indicated in the Destination Designator field of the output header. 


e An agenda, as indicated in the 


default output agenda. 


e Anagenda-specified destination, as indicated by the destination defined for the 
agenda in COMS Utility. Note that a destination specified in the Destination 
Designator field overrides an agenda-specified destination. 


Table 3-2 is a decision table that indicates how COMS routes messages when these 


Agenda Designator field of the output header or a 


items either have assigned values (Y) or do not have assigned values (N), or when the 
presence of an item does not matter (-). An explanation of the action codes follows the 
decision table. 
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Table 3-2. Message-Routing Decision Table: Items with Assigned Values (Yes/No/—) 


' Value Assigned 


Header Destination 


Header Agenda 


Agenda Destination 
Default Output Agenda 


Agenda Destination 


Action Code 


The action codes (values from 1 to 5) in Table 3-2 are associated with the actions COMS 
takes during message routing. These actions are explained in Table 3-3. 


Note: Do not specify an agenda as the default output agenda if it contains 
a processing item that calls OUTPUT_PROC and passes an output 
header that does not specify an agenda. This combination can cause 
recursive calls on the same processing item, eventually causing a 
STACK OVERFLOW error. To prevent this error, a processing item 
that calls OUTPUT_PROC should specify an agenda other than the 
default output agenda in its output header: 


Table 3-3. Message-Routing Action Codes 


Action Code Action Taken 


if the destination is a station, COMS executes any 
agenda-specified processing items associated with the 
message and sends the message to the destination. 


If the destination is a program, the message and the agenda 
designator are placed in the input queue of the program. 
When the program executes a RECEIVE statement, COMS 
removes the message from the queue, applies the 
agenda-specified processing items, and passes the message 
to the program. 


COMS sends the message to the destination. 


In this case, the agenda-specified destination is a program. 
As a result, the message and the agenda designator are 
placed in the input queue of program. When the program 
executes a RECEIVE statement, COMS removes the message 
from the queue, applies the agenda-specified processing 
items, and passes the message to the program. 


continued 
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Table 3-3. Message-Routing Action Codes (cont.) 


Action Code Action Taken 


COMS sends the message to the originating station of the 


last received message after executing any agenda-specified 
processing items associated with the message. 


COMS sends the message to the originating station. 


Sending a Message 


ASEND statement initiates the sending of a message to a station or a program. You can 
use the SEND statement as many times as needed in your program. 


Direct window programs normally run in a window. However, this does not have to be 
true in all cases. It is possible, using the COMS Utility, to define a program that has no 
window associated with it. This is done by not having any agenda with the program as 
its destination. If this “agendaless” program is run, COMS cannot associate it with any 
window, and functions for getting designators and for sending output to stations will not 
work in the same way as if the program ran in a window. 


A program running outside a window can only send to a station if its input came from 
another program running in a window, and the destination is the same station as 
originated the message. The reason for this behavior is that COMS has to know to wach 
terminal window to send the message. 


Using Segmented Output 


To send segmented messages, see Table 3-4 for the COMS options. 


Table 3-4. Segmented Message Options 


Send Option Description 


End-of-Message Indicator (EMI) Unsegmented output that is sent immediately. The 
length of the message is not necessarily the entire 
length of the Message Area variable defined, but the 
length entered into the Text Length field.This option 
is the default value. 


End-of-Group Indicator (EGI) Segmented output that has been held with the ES! 
option is sent along with the current message. Any 
carriage controls that are used here are executed 

only with the. current message. 


continued 
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Table 3-4. Segmented Message Options (cont.) 


Send Option Description 


End-of-Segment Indicator (ESI) With this option, data is taken from the Message 
Area variable and put into a temporary holding 
space the size of the length entered into the Text 
Length field. This is not necessarily the size of the 
entire message area variable. 


The data is then held until one of the following 
takes place: 


e ARECEIVE statement is processed. At this 
time, all segmented output is sent to COMS. 


A SEND statement is processed with the EG! 
option. At this point, all segmented output is 
sent to COMS in the order in which it was 
originally processed. 


A SEND statement that contains the ES! option 
and directs a message to another station is 
processed. In this case, a SEND statement 
ends message queuing for a station because 
COMS queues messages for only one station at 
a time. 


When your program uses segmented output, the MCS waits to transmit any portion ofa _ 
message until the entire message is placed in the output queue. The appropriate EMI or 
EGI message indicator must be included at the end of a message or the MCS does not 
recognize the message and does not send it. After a run has stopped, messages without 
an EMI or EGI at the end are not sent, and are purged from the system. 


If multiple SEND statements are processed with the ESI option, and a SEND statement 
with the EMI option is processed in the middle of these, the SEND statement with the 
EMI option is sent immediately, while the others must wait until one of the ESI output 
conditions is true. As a result, in some cases the messages might appear to be sent in an 
incorrect order. 


The syntax for the use of your SEND statement varies according to the programming 
language you are using. For information on using the SEND statement in your 
programming language, see the appropriate language manual. 


Routing Messages by Specifying a Destination 
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When you include a SEND statement in your program, you can also specify a message 
destination in the output header, unless you want the message to be returned to its 
originating station. . 


To specify a destination, make entries in the output header fields as shown in Table 3~—5. 
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Table 3-5. Output Header Field Descriptions 


Field Description 


Destination Count field This field must contain the value 1, since COMS 
supports a single destination per SEND statement. 


Destination Designator field You can enter a specific destination in this field for 


direct routing. 


Agenda Designator field or Status These fields can contain an agenda designator from 

Value field which a destination can be derived. The destination 
specified in the agenda is overridden by any 
destination specified in the COMS Destination 
Designator field. 


When your program executes a SEND statement, COMS reads the value in the 
Destination Designator field to determine the destination for your outgoing message. 
To specify direct routing, enter a station designator or a program designator. You can 
specify only one destination per SEND statement. 


Routing Messages by Using Agendas 


Agendas are entities of the configuration file. Each agenda can consist of an optional list 
of processing items and an optional destination. Processing items cannot be accessed 
individually by name, but only by group name, that is, in a processing-item list. The 
processing of a message sent by a program before the message reaches its destination is 
referred to as postprocessing. 


To use an agenda on output, you do not need to assign a destination to the message 
because the destination can be determined in the Destination Designator field or the 
predefined destination at installation time. 


Using the Agenda Activity menu of COMS Utility, you can create a default output 
agenda, which might or might not specify a destination. If it does, the destination must 
be a program (or INPUT ROUTER, for transaction-based routing). There can be only 
one default output agenda per window. For additional information on agendas, see the 
COMS Configuration Guide. 


To apply an agenda to a message on output, do the following: 
1. Get the agenda designator by passing the agenda name to the appropriate COMS 


service function. For additional information on COMS service functions, refer to 
Section 4, “Accessing Service Functions.” 


2. Put the agenda designator in the Agenda Designator field of the output header. 
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3. Check the value in the Destination Designator field of the output header to see 
whether it contains the desired destination for the message. The destination 
specified in this field overrides the destination specified by the agenda in the 
Agenda Designator field of the output header. Move a null value or 0 (zero) into the 
Destination Designator field of the output header if you want to use the destination 
specified by the agenda designated in the Agenda Designator field of the output 
header. 


4, UseaSEND statement to send the message and a copy of the output header. 


If your window specification contains a default output agenda, and you want to have that 
agenda applied to your message, steps 1 and 2 are not necessary. 


After you send an outgoing message, the Status Value field of the output header contains 
a value that indicates the status of the message. These values are listed in Appendix A. 


If an error occurred and you failed to clear the error value from the Status Value field, 
the field functions as if you had set it to null (that is, cleared of information) the next 
time your program executes a SEND statement. 


If there is not a designator in the Destination Designator field, the Agenda Designator 
field of the output header, or the Status Value field of the output header, the message is 
directed to the station originating the transaction. 


If the destination of the message is determined to be a station, the processing items 
associated with the agenda are applied to the message immediately. 


If the destination is a program, the message and the agenda designator are placed in the 
input queue of the program. When the message is removed from the queue by COMS 
as a result of the execution of the destination program of a RECEIVE statement, the 
processing items are applied to the message. 


Note: When using agendas to route messages, the program must execute a 
RECEIVE statement from a terminal—not from a program — before 
a default output agenda is applied to messages. Also, second 
default output agendas cannot contain processing items that call 
OUTPUT PROC without supplying a valid agenda designator. 
Those that do are discontinued for exceeding resource limitations 
(R-DS). 


Using Transaction Mode 
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Transaction mode prevents a user from entering input until the response from the 


previous input has been received. There are two agenda attributes that control 
transaction mode: SET TRANSACTION MODE and TRANSACTION-MODE 
AGENDA. Input sent to an agenda that has the SET TRANSACTION MODE attribute 
set to Y in the COMS Utility causes the transaction-mode state for that dialogue to be 
set to 1 (TRUE). A TRANSACTION-MODE AGENDA attribute specifies an optional 
agenda that has a program that processes input from dialogues that are already in 
transaction mode. Only one TRANSACTION-MODE AGENDA attribute can be defined 


for a window. If no TRANSACTION-MODE AGENDA attribute is defined for a window, 
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the transactions are routed to the dialogue of the MARC/1 station. MARC discards the 
input and sends the message “Previous input still in process; message rejected”. 


When an initial input message is associated with an agenda configured for transaction 
mode, all subsequent input to that dialogue is processed as specified, by either the 
TRANSACTION-MODE AGENDA attribute for the current window or the dialogue of 
the MARC/1 station until the transaction mode is cleared. During this process, you can 
switch to another window or dialogue; switching does not affect the transaction mode 
state of the previous dialogue, unless that dialogue is explicitly closed. 


For information on specific values and mnemonics associated with transaction mode, see 
Appendix A. For more information on transaction mode, see the COMS Configuration 
Guide. . 


To clear transaction mode, do one of the following: 


e When you program your transaction processor (TP) or processing item to send a 
message to a dialogue, place a value of zero (FALSE) in the Retain Transaction Mode 
field of the output header. When COMS receives confirmation that the message has 
been delivered, routing is returned to the normal specifications, unless a previous 
SEND statement under transaction mode has set the next input agenda for this 
dialogue. 

e Execute another RECEIVE statement without an intervening SEND statement. 


The transaction mode is cleared and the dialogue is returned to normal routing 
specifications. 


e Close your dialogue so that the dialogue that was in transaction mode no longer 
exists. 


If you do not want your TP or processing item to clear transaction mode, place a value 
of 1 (TRUE) in the Retain Transaction Mode field of the output header when the SEND 
statement is executed. 


The user is responsible for maintaining the transaction-mode state of any dialogue. 
The TRANSACTION-MODE AGENDA attribute merely permits a second program to 
process when transaction mode is already set, and permits the user to clear transaction 
mode when desired. 


If transaction mode, without an associated TRANSACTION-MODE AGENDA remains 
set after the first program terminates, the user must close the window to clear the 
condition. 


If the second program terminates, the user must close the window to clear the condition. 


Routing Messages by Trancode 


You can use the Agenda Designator field of the output header to route messages by 
the trancode (transaction code) contained in the message. A trancode is a sequence 
of characters that can be included in a message. You can also use trancodes to invoke 
processing tasks in an application program within a direct window. 
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To route messages by trancode, place in the Agenda Designator field of the output 
header a designator representing an agenda whose destination is INPUT ROUTER. 
INPUT ROUTER is an entry point in the Router library, which is an internal COMS 
library. ‘Refer to the COMS Configuration Guide for more information about trancodes. 


Because COMS program entities do not have a Trancode Position field, any message 
routed to INPUT_ROUTER from a program defaults to a trancode position of 1. Only 


' messages routed directly from a station use the trancode position value indicated in the 


COMS configuration file station record. Refer to “Determining the Origin of Messages” 
earlier in this section for more information about message origin. 


To use Trancode Security when routing messages by trancode, (as defined on the 
Trancode screen in the COMS Utility), you must establish a current session security for 
the program executing the SEND statement. Session security is established when the 
program executes its first RECEIVE statement. The session security is the intersection 
of the station security and the usercode security of the incoming message. If you 
execute a SEND statement before first executing a RECEIVE statement, the current 
session security is null and COMS rejects the message by returning a value of 98 in the 
COMS-OUT-STATUS-KEY field of the output header. 


Program-Specified Input Agendas 
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Your program can specify the agenda to be applied to the next input message received 
from a dialogue at a particular station. To do this, the Set Next Input Agenda field of 
the output header must be set to 1 (TRUE). At the same time, the Next Input Agenda 
Designator field of the header should contain the designator of the desired agenda. 
COMS changes the agenda when it receives confirmation that the output message was 
delivered to the station. If the Set Next Input Agenda field is 1 (TRUE) and the Next 
Input Agenda Designator field contains a 0 (zero), COMS resets the routing of inputs to 
whatever is specified in the window configuration. 


If the target celeeue is in transaction mode, you can encounter one of the following 
situations: 


e Ifthe SEND statement also clears transaction mode, the next input received from 
the dialogue (after receipt of confirmation) is processed by the agenda in the Next 
Input Agenda Designator field of the SEND statement. 


e Ifthe SEND statement does not clear transaction mode, input continues to be. 
routed according to transaction-mode specifications until a CLEAR is sent. After 
your program receives confirmation of a clearing message, the next input to the . 
dialogue is processed by the previously established input agenda. If more than one 
SEND statement sets the next input agenda, the last one for which confirmation has 
been received goes into effect when transaction mode is cleared. 


Once your program sets the input agenda for a dialogue, that specification remains in 
effect until it is set to another agenda or is reset to normal routing, or until the station 
closes the dialogue. If you have configured this new agenda for transaction mode, this 
agenda is returned to when transaction mode is cleared. For more information on 
transaction mode, see “Using Transaction Mode” in this section. 
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If your destination program aborts, normal COMS error handling takes effect, but the 
programmatically set input agenda is not canceled. 


If your program requests delivery confirmation when it establishes a new input agenda 
for a dialogue, the confirmation message is sent to the destination of the new input 
agenda, not the default agenda. For more information on delivery confirmation, see 
“Requesting Delivery Confirmation” in this section. 


Setting the VT Flag 


The VT (virtual terminal) flag of the output header can be used with a COMS direct 
window, which can have a virtual terminal name when it is used within a CP 2000 
environment. The virtual terminal name describes to BNA how the direct window has 
formatted the output. 


For information on setting the flag using your programming language, see the 
appropriate language manual. 


For information on virtual terminals, refer to the A Series BNA Version 2 Capabilities 
Overview. 


Requesting Delivery Confirmation 


Delivery confirmation is available for network support processor (NSP) stations and for 
CP 2000 stations. This feature of COMS lets a direct window know when a station has 
received a particular message the window has sent. To request delivery confirmation 
for an output message, set the Delivery Confirmation flag to 1 (TRUE) and place unique 
values of your choice in the Delivery Confirmation Key field of the output header before 
executing a SEND statement. 


For information on field names for your programming language, see Appendix B. 


When a program sends a message for which delivery confirmation is requested, COMS 
returns a confirmation result to either the default input agenda of the window that 
generated the output or the agenda established by that message, if the program specified 
a program-specified input agenda. For more information on program-specified input 
agendas, see “Program-Specified Input Agendas” in this section. The confirmation 
result is contained in certain fields of the input header, and in the first three bytes of the 
message area of the destination program of the default input agenda. As soon as COMS 
confirms successful delivery of the message, COMS sends the confirmation result to the 
destination program of the default input agenda. 


If the destination program of the default input agenda is not the same program that 


requested delivery confirmation, a program-to-program message can be sent to the 
requesting program to provide the confirmation result. 
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Results for Successful Messages 


For a message that has successfully reached its destination, COMS confirms the delivery 
of the message by returning a value to the input header in the Function Status field. For 
the meaning of these values and their corresponding mnemonics, see Appendix A. 


COMS also returns a value of 3 to the Text Length field of the input header, and returns 
in the first three bytes of the message area the unique value that was placed in the 
Delivery Confirmation Key field of the output header before the original message was 
sent. 


Results for Rejected Messages 


If the CP 2000 terminal gateway rejects an output message for which delivery 
confirmation was requested, COMS returns a value of 6 in the Text Length field of the 
input header and a value to the Function Status field. For the meaning of the Function 
Status field values and their corresponding mnemonics, see Appendix A. 


A value of 6 is returned to the Text Length field of the input header, indicating that the 
rejection message is 6 bytes long. The first 3 bytes of the rejection message contain what 
was in the Delivery Confirmation Key field when the original message was sent. 


If a break condition causes output from a direct window to be discarded, a break 
notification is sent, but no separate delivery confirmation rejection message is sent for 
each discarded message, even if delivery confirmation was requested. 


Bytes 4, 5, and 6 of the rejection message contain the following information: 


e Avvalue in byte 4 is an error code denoting the reason for the rejection of the 
message. Error values currently defined are the following: 


Value Description 
1 ee Invalid virtual terminal data 
2 Truncated data 
3 Virtual terminal not supported 
4 Out-of-band error 


e Values in bytes 5 and 6 describe the location and origin of the message data that the 
CP 2000 terminal gateway was processing when it detected the error. 
‘Checking the Status of Output Messages 


When your program executes a SEND statement, COMS places a value in the Status 
Value field of the output header to indicate whether an error has occurred. 


Your program should check this value to determine whether an error has occurred 


in the SEND statement or the output header. The meanings of the values and their 
corresponding mnemonics are described in Table A-3. _ 
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Note: Future releases of COMS might add values to the Status Value field 
of the output header. You need to keep this in mind when writing a — 
program that makes use of the values this field can contain. 


Attaching Dynamically to Stations 


You can open dynamically a direct window to a station not currently attached to COMS. 
COMS supports both CP 2000 and network support processor (NSP) stations, which 
might exist on the same system and use the same direct windows. 


Before executing the ENABLE statement, the program must specify the station to which 
the window will be opened. To do this, the program must move a station designator for 
the destination station into the Station Designator field of the input header. 


If the station specified as the destination is currently attached to another program, 

the window of the station is opened but is not made the current window. If you use a | 
CP 2000 station or use the DIAL option on an NSP the window of the station is made 
the current window. 


After COMS has successfully attached a station, the direct window that initiated the 
attachment becomes the default window for the station, overriding all other default 

. window settings. This means that the station automatically starts communication with 
the window that caused COMS to initiate the attachment after the user log-on sequence. 
If the station has a default usercode, the log-on sequence is bypassed entirely. 


COMS is unable to attach an X.25 station or to initiate an X.25 call until the link layer 
has been established. The link layer must be established outside of COMS. 


Using Key Options on Attachment 


Key options are literals defined for use with COMS. Enclose the literal in quotation 
marks when you use it in the statement that enables the input terminal, or when you 
place a literal into a data name you have declared. The key options are 
e KEY DIAL 
e KEY WAIT 

e KEYNOWAIT 
e KEY WAITNOTBUSY 
e KEY WAITDIALOUT 
Use the KEY DIAL option only with NSP stations on switched lines. For attaching NSP 
stations not on switched lines, any option other than DIAL can be used. KEY DIAL 


allows a program to communicate dynamically over a modem with a station, if you place 
values in three fields of the input header as follows: 
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1. Movea station designator for the destination station into the Station field of the 
input header. 


2. Move the phone number of the destination into the Conversation Area field of the 
input header. 


3. Move the length of the phone number into the Text Length field of the input header. 


The other options connected with enabling a station, KEY WAIT, KEY NOWAIT, KEY 
WAITNOTBUSY, and KEY WAITDIALOUT. are significant for CP 2000 stations. Use 
these options to specify how COMS should wait to attach a station and, optionally, the 

hostname on which the station is located. 


If no option is specified or if KEY WAIT is specified, COMS waits for both a physical 
attachment (a dialout) to the station, and for the station to enter a “not busy” state. 


If KEY NOWAIT is specified, COMS attaches the station only if it is not busy and is 
already physically attached. 


If KEY WAITNOTBUSY is specified, COMS waits for the station to enter “not busy” 
state, but does not wait for a physical attachment. 


If KEY WAITDIALOUT is specified, COMS waits for a physical attachment to be made, 
but not for the station to enter “not busy”state. 


If a hostname is specified, COMS attaches the program to a station on that host. Ifa 
hostname is not specified, COMS attaches to a station on the host defined for the station 
in the input header of the program. 


For information on the syntax of the ENABLE statements and key options in your 
programming language, see the appropriate language manual. 


Checking Attachment Status 


To find out the status of a request to attach a station programmatically, write your 
program to query values in the Status Value field and the Function Status field of the 
input header after the program enables a station. The meanings of the values are 
described in Appendix A. 


Detaching Dynamically from Stations 
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You can close dynamically a window to a station, or disconnect a station reached through 
amodem. The station whose window will be closed is the station identified by the station 
designator in the Station Designator field of the input header. 


COMS requests that the CP 2000 terminal gateway detach a station if the following 
conditions prevail: 


e The program disabling a station must be a program in the current window of the 
station being detached. 


e No dialogues to other windows are open, except dialogue 1 of the MARC window. 
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Using Key Options on Detachment 


The key options are literals defined for use with COMS. Enclose a literal in quotation 
marks when you use it in a statement that disables an input terminal or when you place 
a literal into a data name you have declared. The key options are 


e KEY RETAIN 
e KEY RELEASE 

e KEY DIAL 

e KEY DONTCARE 

The KEY RETAIN, KEY RELEASE, and KEY DONTCARE options are for CP 2000 


stations. The KEY DIAL option is for NSP stations on switched lines. For NSP stations 
not on switched lines, any key option other than KEY DIAL can be used. 


If you use the KEY RETAIN option, the CP 2000 terminal gateway retains the physical 
attachment of the station.and terminates only the logical attachment. 


If you use the KEY RELEASE option, the CP 2000 terminal gateway terminates the 
logical attachment and releases the physical attachment (that is, it hangs up the phone). 


If you use neither the KEY RETAIN nor the KEY RELEASE options, the CP 2000 
terminal gateway decides whether to retain or release the physical attachment to the 
station. 


If you use the KEY DIAL option in the ENABLE statement, you should use KEY DIAL 
in the DISABLE statement to detach the station that was reached through the modem. 


If you use the KEY DONTCARE option, the CP 2000 terminal gateway decides whether 
to retain or release the physical attachment to the station. 


For information on the syntax of the DISABLE statements and key options in your 
programming language, see the appropriate language manual. 


Checking Detachment Status 


To find out the status of a request to detach a station programmatically, write your 
program to query values in the Status Value field and Function Status field of the input 
header after the program executes the DISABLE statement. The meanings of the 
values are described. Appendix A. 


Break Condition 


Standard Unisys data comm software issues a break condition when a user enters ?BRK 
_or presses the break key at a station. COMS then processes the break for the current 
and resumed windows of that station. For each such window, any tanked output is 
discarded and a break condition message is routed to the default input agenda of the 
window. See Appendix A for the tables of values and mnemonics for the value placed in 
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the Function Status field of the input header to indicate a break condition message. A 
direct window program obtains this message when it executes a RECEIVE statement 
and there are no other prior queued messages for the window. 


A direct-window program can continue to send output without checking whether a break 
condition message has been routed to it by COMS. As soon as COMS has queued the 
break condition message to the program, COMS stops discarding any messages sent by 
the program. Therefore, any output sent by the direct window program after this point 
is displayed at the station. 
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Accessing Service Functions 


This section applies to the full-featured version of COMS. If you have developed your 


programs using a previous release of COMS, see the service functions in Appendix F. For 
further information about the entities and designators discussed in this section, see the 
COMS Configuration Guide. 


This section describes the service functions or entry points that COMS provides. Entry 
points are procedures that allow access to a library code file. Service functions allow you 


to obtain information on all of the entities in the configuration file. 


All entities in the COMS configuration file have designators and can be used in service 
function calls. For each entity, you can use your program to receive information about 


the following: 


e Entity name 


e Installation data 


For some entities, you can receive the following additional information: 


Entity 


Program 


Station 


Station List 
Usercode 


Window 


Information Available 

Current input queue depth 

Mix numbers for active copies 
Response time aggregate 
Response time for last transaction 
Security designator 

Total number of input messages handled 
Device designator 

Logical station number (LSN) 
Screen size 

Security designator 

Virtual terminal (VT) type 
Stations in list 

Security designator 

Current number of users 


Maximum number of users 


Application programs can communicate with COMS through a direct-window interface 


by using a COMS header. Refer to Section 3, “Communicating with COMS through 
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Direct Windows” for information on this procedure. This interface also allows 
communication between COMS and application programs to be enhanced by the use 
of designators. A designator is a binary data type that can be included in a program 
to control messages symbolically rather than directly with entities in the data comm 
environment. 


Each COMS service function is an integer procedure of the COMS Library. When you 
use a service function, you can exchange either a name that represents an entity for a 
designator or a designator for a name that represents an entity. 


Note: Always use the space character to initialize arrays for entity names 
in your programs. When COMS returns an entity name in response 
to a service function call, it uses space characters to blank-fill the 
remainder of the array. Thus, programs that initialize and scan for 
null characters will fail. 


Before you call service functions, you need a general understanding of how they use 
designators and names, and what their input and output parameters are. 


Designators and Names 


The service functions use designators to constitute an internal code understood by 
COMS. The designators are used in the table structure of the system. Because the 
layout of COMS designators may change with each software release, a program should 
never preserve any designator across executions. Do not, for example, use designators 
as keydata in a database. 


The COMS service functions enable you to 


e Translate designators to names that represent COMS entities. 

e Translate names that represent COMS entities to designators. 

e Obtain additional information about the designator passed to the service function. 
You can obtain designators from the message header of an application program or from 


those service functions that allow you to translate names to designators. (See Section 3, 
“Communicating with COMS through Direct Windows.”) 


Input and Output Parameters 
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When you pass a name or a designator to a service function, the name or designator is 
used as an input parameter. The COMS Library returns output parameters and function 
values. All service functions return an integer specifying the result of the call in an area 
you define to receive your result. For the syntax for your programming language, see 

the appropriate language manual. For information on the specific result values and 
mnemonics of service function calls, see Appendix A. 


You can get designators from several different places. You can get them from various 
fields of the input header. (See Section 3, “Communicating with COMS through Direct 
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Windows,” for a discussion of header fields.) You can also get designators by using the 
following service functions: 

e GET DESIGNATOR _USING NAME 

e GET DESIGNATOR_USING DESIGNATOR 

e GET _DESIGNATOR ARRAY USING DESIGNATOR 

Agenda, trancode, installation data, and station designators are different from 
designators that represent other COMS entities. Whereas a program, for example, can 
always obtain the same valid designator that identifies only the program itself, each 
designator for the agenda, trancode, and installation data entities must uniquely identify 
a particular combination of a window and that entity. In the same way, each station — 


designator uniquely identifies a particular combination of a window, a dialogue, and a 
station. 


Always comply with the following restrictions to make sure that you get valid designators 
when using the GET_DESIGNATOR_USING_NAME service function for agendas, 
trancodes, and installation data. 

e Call this service function only from direct-window programs. 


e Call the service function only after a direct-window program has enabled an input 
terminal. 


e Do not allow a processing item to call the service function until the library code of the 
processing item has executed a FREEZE statement. 


Use of Installation Data 


Installation data are used to attach special data to specific configuration elements. 

The data can take the form of comments or program-accessible fields to be used by 

user-created applications. Typical uses of installation data would include: 

e District or branch number for location of a station. 

e Test or production mark for a program. | 

e Aset of data to group entities in the configuration according to some 
installation-specific rules. — 


To the programmer, installation data items are handled in the same manner as the other 
items in the COMS configuration. Some differences, however, need to be explained. 
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The items for an installation data entity are accessed using the solowme service function 


calls: 
Service Function Call Items Accessed 
GET_INTEGER_USING_DESIGNATOR Accesses the following items one at a time: 


e = Installation_Integer_1 — 
e = Installation_Integer_2 
e Installation_Integer_3 
e = Installation_Integer_4 


GET_INTEGER_ARRAY_USING_DESIGNATOR Uses Installation_Integer_All to concatenate 
all the items listed under 
GET_INTEGER_USING_DESIGNATOR. 


GET_STRING_USING_DESIGNATOR Accesses the following items one at a time: 
e = Installation_String_1 
e Installation_String_2 
e = Installation_String_3 
e = Installation_String_4 
e = Installation Hex_1 


e = Installation_Hex_2 


The designator passed to these service functions can be one of the following: 


e Aninstallation data entity designator, which you can obtain from an installation data 
name by using the GET_DESIGNATOR_USING_NAME service function or using 
the GET. DESIGNATOR. USING. DESIGNATOR service function. In this case, the 
entity is used in a direct manner to access the data. 


e Any other entity designator that has a link to an installation data entity. In this case, 
the link is used as the path to the data. 


For example, these two methods of getting an installation integer for a station designator 
produce the same result: : 


Method 1 


1. Have a station designator. 


2. Use the GET INTEGER USING DESIGNATOR service function with the station 
designator. 


Method 2 


1. Have astation designator. 


2. Use the GET _ DESIGNATOR_USING_DESIGNATOR service function with the 
station designator and the request for Installation_Data_Link. 
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3. Use the GET INTEGER USING DESIGNATOR service function with that 
installation data designator. 


The following sequence of steps gets an installation integer for a station when the station 
is linked to an installation data item that in turn is linked to another installation data 
item containing the installation integer: 


Have a station designator. 


Use the GET_ DESIGNATOR USING DESIGNATOR service function with the 
station designator and the request for Installation_Data_Link. 


3. Use the GET_DESIGNATOR_USING_DESIGNATOR service function with the 
installation data designator received in step 2. 


4. Use the GET INTEGER USING_DESIGNATOBR service function with the 
installation data designator from step 3. 


Because installation data are application dependent, each installation data entity resides 
in a particular window. However, an entity can have a window of “ALL” specified, in 
which case it resides in all windows. Therefore, if a program running in one window 

- requests installation data, it might get different data than would a program running in 
another window. COMS keeps track of where each installation date entity resides so 
that the program does not have to have any any knowledge of the different windows. 


Explanation of Mnemonics for Service Functions 


For each service function, the allowable mnemonics for entities are listed later in this 
section. Table 4~1 provides brief descriptions of each mnemonic. 


Table 4—1. Descriptions of Service Function Mnemonics 


Mnemonic Description — 


Aggregate_Response_Time Sum of transaction response times. Accumulated by 
COMS. 


Convention Connection default convention. Assigned by MARC. 


Current_User_ Count Number of users on a window. Kept by COMS. 


Installation Data_Link An entity pointed to by another COMS entity. 
Assigned by the COMS Utility. 


Installation_String_1, Strings of installation-specific data. Assigned by the 
Installation_String_2, COMS Utility. 
Installation String_3, 
Installation_String_4, 
Installation_Hex_1, Installation_Hex_2 


continued 
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Table 4-1. Descriptions of Service Function Mnemonics (cont.) 


Mnemonic Description . 


Installation_Integer_1, Integers of installation-specific data. Assigned by 
Installation_Integer_2, COMS Utility. 

installation_Integer_3, 

Installation_Integer_4 


Language’ Connection default language. Assigned by MARC. 


Last_Response_Time Program response time in milliseconds for the last 
transaction handled. Kept by COMS. 


LSN Logical station number. Assigned by the data comm 
subsystem. 


Maximum_User_Count Maximum allowed number of users on a window. 
Assigned by the COMS Utility. 


Mixnumbers Array of mix numbers for the copies running for the 
program. Kept by the operating system. 


Screen Size . Statically configured attribute that represents the 
size of the terminal attached to the system. 


Statistics A gathering of program statistics. Values 
accumulated by COMS. 


Total_Transaction_Count Number of transactions received by the program 
since COMS initialized. Kept by COMS. 


Transaction_Queue_Depth Number of transactions in queue for the program. 
Kept by COMS. 


Virtual Terminal Name of the terminal’s text editor in the 
communications processor. Kept by COMS. 


Calling Service Functions 


You can call the COMS service functions with application programs and processing items. 
For the specific syntax for calling a service function using your programming language, 
see the appropriate language manual. 


The service functions are 


¢ CONVERT TIMESTAMP 
° GET DESIGNATOR ARRAY USING DESIGNATOR 
e GET DESIGNATOR USING DESIGNATOR 

° GET DESIGNATOR USING NAME 

¢ GET_INTEGER_ARRAY USING DESIGNATOR. 
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e GET INTEGER USING DESIGNATOR 

e GET_NAME USING _DESIGNATOR 

e GET REAL ARRAY 

e GET STRING USING DESIGNATOR 

e STATION_TABLE ADD 

e STATION TABLE INITIALIZE 

e STATION TABLE SEARCH 

e TEST _DESIGNATORS 

The station table service functions that appear in the previous list perform differently 
than the other service functions. Specifically, the station table functions provide the 
user-application program with a unique integer value for a given station designator. 
When provided a station designator, these functions perform the following tasks: 

e Allocate a location (index) in a table 

e Preserve the index within the table 

e Supply the table index to the application program on request 

The table index is owned by the TP and is passed to these station table service functions 
on each call. The table can be searched by multiple inquirers concurrently. This table 


can also be searched while it is being updated. However, the inquirer is responsible for 
preventing concurrent updates. 


The table can be resized by the functions. However, the table size is generally more 
accurate when the caller declares an initial size based on the number of stations that 
might be added to the table. 


The following subsections describe each service function and provide information on how 
to use the service functions to obtain information on specific entities. 


CONVERT_TIMESTAMP 


You can use this service function to convert a COMS timestamp, TIME(6), into a form 
that you can read. 


The declaration in COMS is as follows: 


INTEGER PROCEDURE CONVERT_TIMESTAMP(ENTY_TIMESTAMP, 
ENTY_MNEMONIC, 
ENTY_TIME) ; 


Parameters 


ENTY_TIMESTAMP is the TIME(6) timestamp that is returned in the Timestamp field 
of the input header. 


8600 0650-000 4-7 


Accessing Service Functions 


ENTY MNEMONIC represents the information you are requesting. The allowable 
mnemonics are as follows: 


e The Date mnemonic returns the date in the form of MMDDYY. 


e The Time mnemonic returns the time in the form of HHMMSS. 


ENTY_TIMB is the array where the result from COMS is returned. 


GET _DESIGNATOR_ARRAY_ USING DESIGNATOR 


You can use this service function to get a designator list representing the list of stations 
associated with the station-list designator passed as the input parameter to this function. 
Because the station list is not a field of the header, you must first obtain the designator 
representing the station list by using the GET_DESIGNATOR_USING_NAME service 
function. Then use the station list designator supplied by that function as the designator 
variable in the GET_DESIGNATOR_ARRAY USING DESIGNATOR function. 


The declaration in COMS is as follows: 


INTEGER PROCEDURE GET DESIGNATOR _ARRAY_USING DESIGNATOR © 
(ENTY_DESIGNATOR, | 
ENTY_DESGTOTAL, 
ENTY DESGVECTOR) ; 


Parameters 


ENTY_ DESIGNATOR represents the structure. The allowable designator is station list, 
which returns a list of stations. 


ENTY_DESGTOTAL is the total number of designators in the list by COMS. 


ENTY DESGVECTOR is the list in which the designators are returned. 


GET DESIGNATOR USING DESIGNATOR 


4-8 


You can use this service function to get a specific designator out of the structure 
represented by a designator. The designator to be passed as an input parameter can be 
any designator. COMS looks at the designator and the mnemonic passed and returns the 
designator information associated with the two. 


The declaration in COMS is as follows: 


INTEGER PROCEDURE GET_DESIGNATOR_USING DESIGNATOR(ENTY DESIGNATOR, 
| ENTY_MNEMONIC, 
ENTY_DESGRES) ; 


Parameters 


ENTY_DESIGNATOR represents the structure from which you want to get a 
designator. 
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ENTY MNEMONIC is the designator type you are requesting. The allowable mnemonic 
and designator combinations are as follows: 


Mnemonic Entity 

Device Station 

Installation. Data_Link All entities 

Security_Category Station, program, and usercode 


ENTY_DESGRES is the designator returned by COMS. 


GET_DESIGNATOR_USING_NAME 


You can use this service function to convert a COMS entity name to a COMS designator. 
If you have a name that represents an entity, you can get the designator associated 

with that name. For instance, you could use this service function if you want to senda 
message through an agenda for which you have the name. You cannot put the agenda 
name in the output header, but you can obtain the agenda designator by using this 
service function. 


If a program requires the designator of the window under which it is operating, you can 
place an asterisk (*) in the first column of the parameter you pass for the window name 
and call GET DESIGNATOR USING_NAME. COMS will return the window designator 
for the window associated with the calling program. 


If GET_DESIGNATOR_USING_NAME receives an input name of 17 blanks ina 
usercode inquiry, GET_DESIGNATOR_USING_NAME will return the superuser 
designator. For more detailed information on superuser usercode and superuser 
designator, refer to the A Series Security Administration Guide. 


The declaration in COMS is as follows: 


INTEGER PROCEDURE GET_DESIGNATOR_USING NAME(ENTY_NAME, 
; ENTY_MNEMONIC, 
ENTY_ DESIGNATOR) ; 


Parameters 


ENTY NAME is the name of the entity. For the agenda, trancode, and installation data 
entities, the string for the entity name should include the window name if the program 
calling the service function is running in another window or is run outside of COMS. For 
example, when you pass the entity name, you should provide the following: 


<agenda name> of <window name> 
For the installation data entity, if a window is not specified, and if the window in which 


your program is running has no entity of the same name, the installation data with 
window value equal to “ALL” is picked up, since it is the default. 
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ENTY MNEMONIC is the mnemonic for the entity you are obtaining. The mnemonics 
are listed in Appendix A. Mnemonics are allowed for all entities that have a designator. 


ENTY DESIGNATOR is the designator COMS returns to you. 


GET _INTEGER_ARRAY_USING_ DESIGNATOR 


You can use this service function to get a list of integers from the structure represented 
by a designator. 


The declaration in COMS is as follows: 


INTEGER PROCEDURE GET_INTEGER_ARRAY USING DESIGNATOR 
(ENTY DESIGNATOR, 
ENTY MNEMONIC, 
ENTY_INTEGERTOTAL, 
ENTY_INTEGERVECTOR) ; 


Parameters 


ENTY DESIGNATOR represents the structure from which you want to get a list of 
integers. 


ENTY_MNEMONIC describes which integer list you are requesting. The allowable 
mnemonic and designator combinations are as follows: 


Mnemonic . | Entity 
Installation_Integer_All All entities 
Mixnumbers Program 


ENTY_INTEGERTOTAL is the number of integers returned in the vector. 


ENTY_INTEGERVECTOR is the list itself. 


GET _INTEGER_USING_DESIGNATOR 
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You can use this service function to get a specific integer out of the structure represented 
by a designator. 


The declaration in COMS is as follows: 


INTEGER PROCEDURE GET_INTEGER_USING DESIGNATOR(ENTY DESIGNATOR, 
ENTY_MNEMONIC, 
ENTY_INTEGER) ; 


Parameters 


ENTY_ DESIGNATOR is the designator representing the structure from which you want 
to get a specific integer. 
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ENTY_ MNEMONIC describes which integer you are requesting. The allowable 
mnemonic and designator combinations are as follows: 


Mnemonic Entity 
Aggregate _Response_Time Program 
Current_User_Count Window 
Installation_Integer_All All entities 
Installation_Integer_1 All entities 
Installation_Integer_2 All entities 
Installation_Integer_3 All entities 
Installation_Integer_4 All entities 
Last_Response_Time Program 
Logical_Station_ Number Station 
Maximum_User_Count Window 
Mixnumbers Program 
Screen_Size Station 
Total_Transaction_Count Program 
Transaction_Queue_Depth Program 
Virtual_ Terminal | | Station 


ENTY_INTEGER is the integer returned by COMS. 


GET_NAME_USING DESIGNATOR 


You can use this service function to convert a COMS designator to the COMS name for 
that designator. For instance, you might want to know the name of the terminal that 
sent a message if you use the terminal names as a unique key. 


The declaration in COMS is as follows: 


INTEGER PROCEDURE GET_NAME_USING_DESIGNATOR(ENTY_DESIGNATOR, 
. ENTY_NAME) ; 


If GET NAME USING DESIGNATOR in a usercode inquiry receives the designator of 


the superuser, then GET NAME USING_DESIGNATOR returns a name of 17 blanks. 
For more detailed information on superuser, refer to the Security Administration Guide. 


Parameters 


ENTY_DESIGNATOR is the designator. All designators are allowed. 
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ENTY_NAME isa string of 1 to 17 characters, except for station names, which are up 
to 255 characters, where the name is to be returned by COMS. If the station name 
returned by COMS is shorter than the user array, COMS fills the user array with blanks. 


GET_REAL_ARRAY 
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You can use this service function to get a data structure with no connection to any entity. 
You can monitor response times on your system through the use of statistics. 


Note: This service function cannot be used by the RPG programming 
language. However, the results provided by this service function can 
be covered by using the GET_INTEGER_USING_DESIGNATOR 
service function and performing a series of separate calls. 


The declaration in COMS is as follows: 


INTEGER PROCEDURE GET REAL_ARRAY(ENTY_MNEMONIC, 
ENTY_REALTOTAL, 
ENTY_REALVECTOR) ; 


Parameters 


ENTY _MNEMONIC is the data structure that you are requesting. The allowable 
mnemonic is Statistics. It returns a table, each entry of which has six elements as 
follows: 

e Adesignator for the entity for which the statistics are given 

e The type of entity as follows: 


Value Entity 
1 © Direct-window program 
2 Remote-file program 
3 MCS window 


e Transaction queue depth (direct window only) 

e Total transaction count 

e Last response time in milliseconds (direct window only) 

° Aggregate response time in milliseconds (direct window only) 

This information is also provided by the Statistics window. However, if you want to 


generate your own reports, the service function is available for your use. For more 
information on the Statistics window, see the COMS Configuration Guide. 
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ENTY_REALTOTAL is the total number of elements returned in the array —six times 
the number of table entries for statistics. 


ENTY REALVECTOR is the array where the information is returned from COMS. The 
size of the array is six words for each running direct-window program plus six words for 
each MCS window. 


GET _STRING_USING_ DESIGNATOR 


You can use this service function to get an EBCDIC string out of the structure 
represented by the designator. This service function returns strings that you can have 
set up as installation data in the COMS Utility. 


This service function is used to enable a multilingual program to communicate with 
multiple stations by determining the language and convention attributes of the 
stations. If an application program uses the GET STRING_USING DESIGNATOR 
service function to retrieve the attribute for a station, and if the station uses the 
default system attribute, then the service function returns an error value of 4 
(UMBRELLA NONDATA ERRORV). 


For more information on the language and convention attributes, refer to the COMS 
Configuration Guide. 


The declaration in COMS is as follows: 


INTEGER PROCEDURE GET_STRING USING DESIGNATOR(ENTY_ DESIGNATOR, 
ENTY_MNEMONIC, 
ENTY_STRINGTOTAL, 
ENTY STRING) ; 


Parameters 


ENTY_ DESIGNATOR is the designator representing the structure from which you want 
to get the string. 


ENTY MNEMONIC describes which string you are requesting. The allowable 
mnemonic and designator combinations are as follows: 


Mnemonic ' Entity 

CONVENTION Station 

Installation_String_1 All entities 
Installation_String_2 | All entities 
Installation_String. 3 All entities 
Installation_String_4 All entities 
Installation_Hex_1 All entities 
Installation_Hex_2 All entities 


LANGUAGE ; Station 
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ENTY_ STRINGTOTAL is the number of valid characters in the string returned by 
COMS. 


ENTY_STRING is the string returned by COMS. This designator returns the requested 
LANGUAGE or CONVENTION attribute string. 


If either the LANGUAGE or CONVENTION mnemonic is specified, the station 


designator obtains the corresponding station table index of the entry for that station. _ 


After the station index has been determined, the station table entry is checked to 
determine if the station is logged on. Ensuring the log-on status requires checking that 
the STA_UCODEINX field is set to a nonzero value. If the STA_UCODEINX field is 
set to zero, the procedure returns a value indicating a failure. If the STA_UCODEINX 
field is set to a nonzero value, then the attribute string required is returned in 
ENTY_STRING. If no other attribute has been specified, the system default attribute is 
returned. 


STATION. TABLE_ADD 


This service function is used to add a station designator to the table. The table and the 
station designator are passed to the procedure and a unique index is returned. 


Note: This service function cannot be used by the RPG or Pascal 
programming languages. 


The declaration in COMS is as follows: 


PROCEDURE STATION TABLE_ADD (STATION_HASH, 
STATION _DESIGNATOR) ; 


Parameters 
STATION_HASH is the table of station designators. 


STATION DESIGNATOR is the station designator to be added to the table. 


STATION TABLE INITIALIZE 


4-14 


This service function is used to initialize the station table into which the station index 
values are placed. You pass to this procedure the table and a table modulus. (The table 
is implemented as a hash table.) The modulus is used to determine the density and 
access time of the table. For fast access and sparse table population, select a modulus 
that is twice the maximum number of table entries. For slow access and compact table 
population, select a modulus that is half the maximum number of entries. 


Note: This service function cannot be used by the RPG or Pascal 
‘programming languages. 
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The declaration in COMS is as follows: 
PROCEDURE STATION TABLE INITIALIZE (STATION_HASH, 
SHMOD) ; 


Parameters 
STATION _HASH is the table of station designators. 


SHMOD is the table modulus. 


STATION TABLE SEARCH 


The STATION TABLE SEARCH service function is used to locate a service designator. 
This service function locates a service designator by receiving a station table and then 
searching the available service designators within the table. If the service function 

finds the service designator, the index to the table is returned. A return value of zero 
indicates that the station designator was not found. 


Note: This service function cannot be used by the RPG or Pascal 
programming languages. 


The declaration in COMS is as follows: 


INTEGER PROCEDURE STATION _TABLE_SEARCH (STATION_HASH, 
STATION_DESIGNATOR) ; 


Parameters 
STATION HASH is the table of station designators. 


STATION DESIGNATOR is the station designator to be located. 


TEST _DESIGNATORS 


You can use this service function to test whether a designator is part of a structure 
represented by another designator. For example, when you pass a security designator 
and a security-category designator to this service function, COMS tells you whether the 
security category represented by the security-category designator is valid for the session 
represented by the security designator. This service function can also be used for the 
security designators of stations and usercodes. 


The declaration in COMS is as follows: 


INTEGER PROCEDURE TEST_DESIGNATORS(ENTY_DESIGNATOR_1, 
ENTY_ DESIGNATOR 2); ; 
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Parameters 


ENTY_DESIGNATOR_1 and ENTY_DESIGNATOR_2 represent the two entities you 
are trying to match, or whose relationship you want to determine. The order in which 
you pass the designators does not matter. Allowable combinations of designators are as 
follows: 

e Device-type list and device type 


e Security category and security 
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A processing item is a procedure you can use to process a message either before an 
application program receives it or after an application program sends it. Only programs 
that use the direct-window interface to COMS can receive and send messages that 

use processing items. Processing items reside in processing-item libraries you create. 
Processing items are written in ALGOL. However, any programming language that 
ALGOL can call can use the ALGOL shell to write processing items. For information on 
using the ALGOL shell to write processing items, see Appendix E. 


To integrate processing items into your installation, you need to understand the 
functions and interrelationships of the entities in the COMS configuration file. For more 
information on COMS entities, see the Section 1, “Introduction to COMS.” Also refer 

to the COMS Configuration Guide for more information about the COMS entities and 
what roles they play in message routing. 


You can use rocesaiie items to preprocess and postprocess the messages that are 
received and sent by the stations and programs in a data communications network. To 
preprocess a message, the COMS configuration file must have been defined to apply a list 
of processing items to a message before it is received by a program. Refer to the COMS — 
Configuration Guide for information on defining the configuration file. To postprocess 

a message, specify programmatically which agenda you want applied to the message a 
program is sending. Refer to Section 3, “Communicating with COMS through Direct 
Windows,” for more information on the necessary programming steps. 


The following are among the possible uses for processing items: 


e Translating a message from one format into another 
e Generating multiple messages to be received or sent from a single message 


e Redirecting a message to a destination different from the one indicated by the 
system configuration or specified programmatically 


e Segmenting long messages into several shorter messages, or r grouping several short 
messages into one large message 


e Performing security checks on messages 

e Auditing messages 

e Formatting input and output messages 

For a processing item to process a message, the message must be received or sent 
through a COMS direct window and must be associated with an agenda. You can apply 
processing items only by using agendas, because programs you write cannot directly 
call processing items. Refer to Section 3, “Communicating with COMS through Direct 


Windows,” for information about the direct-window interface to COMS and for the 
function of agendas in message routing, preprocessing, and postprocessing. 
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The next two parts of this section, “How Processing Items Alter Message Data” and 
“Creating a Processing-Item Library,” provide a description of how processing items 
work and what structures are necessary before you can write processing items. For a 
discussion of how to write processing items, refer to “Creating a Processing Item Using 
the ALGOL Specification” in this section. 


How Processing Items Alter Message Data 


The actual preprocessing or postprocessing of a message occurs when the COMS 

Agenda Processor library passes the message data and the associated header to a 
processing-item library. The route a message takes to reach the Agenda Processor 
library differs depending on whether the message is to be preprocessed or postprocessed. 
The following subsections describe the routes that messages take to reach the Agenda 
Processor library and the role the library plays in message processing. 


Routing of a Message for Preprocessing 


When an incoming message first enters the COMS system, the COMS Router library 
determines which agenda to apply to the message. If the message contains a trancode, 
then the trancode specifies the agenda. If the message does not contain a trancode, then 


the Router library applies the default input agenda of the window to which the message 
is destined. 


An agenda must specify the destination for the message and can specify a list of 
processing items to be applied to the message. According to the destination specified 

by the agenda, the Router library places the message in the queue of the destination 
program. When the destination program executes a RECEIVE statement, the 
transaction processor (TP) library or the database (DB) library is called automatically. 
Next, the TP or DB library determines whether any processing items need to be applied 
to the message in the queue. If processing items do need to be applied, the TP or DB 
library calls the COMS Agenda Processor library. 


Refer to “How the Agenda Processor Handles a Message” later in this section to find 
out what actions the Agenda Processor library takes when it is called by the TP or DB 
library. The actions taken by the Agenda Processor library are the same regardless of 
whether a message is being preprocessed or postprocessed. 


Routing of a Message for Postprocessing 
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When a program executes a SEND statement to send a message out to a station or 
another program, the TP or DB library is called automatically. Next, the TP or DB 
library determines what agenda is associated with the message. An agenda must have 
been specified either programmatically in the Agenda Designator field of the output 
header before the SEND was executed or by specification of’a default output agenda for 
the window. If no agenda was specified, the TP or DB library applies the default agenda 
of the direct window that is sending the message. 


Sending a program-to-station message is the simplest case of routing an outgoing 
message. In this case, if the specified agenda contains a processing-item list, the TP or. 


8600 0650-000 


Processing Items 


DB library calls the Agenda Processor library before sending the postprocessed message 
to its destination. 


For a program-to-program message, the TP or DB library places the outgoing message 
into the queue of the destination program. When the destination program executes a 
RECEIVE statement, the TP or DB library calls the Agenda Processor library if the 
specified agenda contains a processing-item list. 


If you route an outgoing message by trancode, you must have specified, either in the 
Agenda Designator field of the output header of the program or as the default output 
agenda for the window, an agenda with no processing-item list whose destination is 
INPUT_ROUTER. Next, the TP or DB library replicates the logic of the Router library 
to determine which agenda is associated with the trancode in the message. Once the 
agenda is known, the TP or DB library calls the Agenda Processor library if the agenda 
contains a processing-item list, before sending the message to its destination. Refer to 
“Routing Messages by Specifying a Destination” and “Routing Messages by Trancode” 
in the Section 3,“Communicating with COMS through Direct Windows,” for more 
information about specifying INPUT ROUTER as an agenda. 


The following subsections describe what actions the Agenda Processor library takes 
when it is called by the TP or DB library. The actions taken by the Agenda Processor 
library are the same regardless of whether a message is being preprocessed or 
postprocessed. 


How the Agenda Processor Library Handles a Message ~ 


Only the TP or DB library can call the Agenda Processor library in response to an 
incoming message entering COMS or a program executing a SEND statement. When 
the TP or DB library calls the Agenda Processor library, it passes to the Agenda 
Processor library the message data and associated header for the message being 
preprocessed or postprocessed. 


If the specified agenda contains a processing-item list, the Agenda Processor library calls 
each processing item on behalf of the message, passing as parameters the message data 
and the associated header. Thus, the processing item can modify the memory areas, 
called the message data array and the header array, which are declared in the program 
that is receiving or sending a message. 


When a single processing item completes all its processing tasks, it exits back to the 
Agenda Processor library. If the Agenda Processor library calls a second processing item, 
the second item sees the same memory areas as they were modified by the previous 
processing item. When all processing items in a list are completed, the Agenda Processor 
library exits back to the TP or DB library, which exits back to the program executing a 
RECEIVE statement or a SEND statement. 


8600 0650-000 5-3 


Processing Items 


Example of Processing Items Used for Postprocessing 


Following is an example of three processing items in a processing-item list that work 
together to postprocess a message: 


e The first processing item fetches instructions from disk for creating a particular 
format. 


e The second processing item uses the instructions to create the format and the 
message that the user receives. 


e The third processing item stores the message on disk so it can be recalled if needed. 
When the third processing item completes its task, COMS automatically sends the 
format to the user’s terminal. 


Creating a Processing-Item Library 


You must create a processing-item library before writing individual processing 
items. The following paragraphs discuss the conventions to follow when creating 
processing-item libraries and how to choose a library configuration. 


Conventions for Creating Libraries 
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Follow these conventions when you create processing-item libraries for a 
multiple-program environment: 

Write processing-item libraries in ALGOL only. 
2. Use these ALGOL library attributes when writing the library code: 


$SET SHARING = SHAREDBYRUNUNIT 


FREEZE (PERMANENT) 


Refer to the A Series ALGOL Programming Reference Manual, Volume 1: Basic 
Implementation for information about writing ALGOL libraries. 


3. One processing-item library cannot call another processing-item library that is 
known to COMS. 


4. An application program cannot directly call a processing-item library. Only a 
COMS internal library called the Agenda Processor library can directly call a 
processing-item library. 


5. A program written in a language other than ALGOL can make use of 
‘processing-item libraries if the language has a library interface. Although no 
program except the Agenda Processor library can directly call a processing-item 
library, a language must have a library interface in order to use the direct-window 
interface to COMS. . 
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Choosing a Library Configuration 
There are two basic configurations you can use when creating processing-item libraries: 


e Multiple libraries that each contain only a few entry points 
e Asingle library, or only a few libraries, that each contain numerous entry points 


These configurations are described in the following text. Read this information before 
choosing a library configuration. 


Creating Multiple Libraries Containing Few Entry Points 


The advantages and disadvantages of creating multiple libraries that each contain only a 
few entry points are as follows: 


e Multiple libraries are easy to maintain. If you include as few entry points as possible 
in each library, then changing, adding, or deleting libraries or entry points has little 
impact on other system structures. 


e Multiple libraries require more memory than a single library that contains all 
combined entry points. 


Creating a Single Library with Multiple Entry Points 


The advantages and disadvantages of creating one library, or only a few libraries, 
containing multiple entry points are as follows: 


e Using few libraries minimizes the number of memory stacks running on your system. 


e Ifall functions that you want performed share a common state or common 
declarations, such as a common file declaration, then making all these functions 
entry points of the same library is efficient and might be mandatory in some cases. 


e Anentry point of a processing-item library can call other entry points or internal 
procedures of the same library. These entry points and procedures can share 
common logic. In contrast, an entry point of one processing-item library cannot 
share logic with or call an entry point of another processing-item library. 


Example of a Single Library Containing Multiple Entry Points 


Following is an example of a processing-item library with two entry points that can 
refresh a screen if for some reason the original screen is lost: 


e One entry point is called right after the original screen is transmitted to the terminal 
of the user. This is a postprocessing entry point that saves a copy of the screen on 
disk. 


e Ifthe user’s terminal must be turned off and then turned back on, the REFRESH 
command is entered. 
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e The second entry point of the processing-item library detects the entry of the 
REFRESH command, and retrieves the copy of the screen that is saved on disk. 
Then COMS automatically sends the copy of the screen to the user’s terminal. 


In this case, there are two entry points in one processing-item library because eae entry 
points share a common declaration for the disk file. 


Creating a Processing Item Using the ALGOL 
Specification 


You should write your processing item in ALGOL. However, any programming 
language that ALGOL can call can use the ALGOL shell to write processing items. For 
information on using the ALGOL shell to write processing items, see Appendix E. 


To create the processing item, use the following ALGOL specification: 


REAL PROCEDURE PROC_ITEM(STATE, 
HEADER, 
USER_DATA, 
TEXT_1, 
TEXT 2, 
OUTPUT PROC) ; 
REAL STATE; ca 
ARRAY HEADER[S] ; 
EBCDIC ARRAY USER _DATA[@], TEXT_1[8], 
TEXT _2[8]; 
REAL PROCEDURE OUTPUT_PROC(STATE, 
HEADER, 
TEXT_1, 
TEXT_2); 
REAL STATE; 
ARRAY HEADER[8] ; 
EBCDIC ARRAY TEXT_1[@], TEXT_2[9]; 
FORMAL; 
BEGIN 


END; 


Use this REAL procedure to declare the required parameters for each processing 

item you create. The required parameters are STATE, HEADER, USER_DATA, 
TEXT 1, TEXT 2, and OUTPUT_PROC. Although you can name the procedure and the 
parameters anything you wish, you must declare the parameters in the order shown 
above. The Agenda Processor library passes these parameters to your processing item 
when submitting a message for processing. 


Whether or not you intend to use all the parameters shown in the specification, you must 
declare all of them, including the formal procedure called OUTPUT_PROC. Even if you 
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want a processing item to do nothing but call OUTPUT_PROC, you must declare the 
entire PROC_ITEM procedure. 


The Agenda Processor library passes each of the six parameters when calling a 
processing item so that the processing item can modify the message data. Each 
parameter is described in the following subsections. 


STATE Parameter 


The STATE parameter is a REAL variable. One of its purposes is to indicate which one 
of the following parameters holds the newest message data: 


e USER DATA 
e TEXT 1 
e TEXT 2 


When the Agenda Processor library calls a processing item, it sets the value of 

STATE.[15:02] to tell the processing item where the message data is. The Agenda 

Processor library also sets STATE.[07:08] to a value of 0 (zero) or 1 to indicate whether 

the message is being received or sent. Finally, the Agenda Processor library sets 

STATE.[13:06] to the index of the first word of the Conversation Area field in the 
HEADER parameter. 


A processing item must change the value of STATE.[15:02] to one of the values defined 
in Table 5-1 whenever it moves the newest message data from one data area to another. 
If it does not modify the message data at all, do not change the value of any field in the 
STATE parameter. 


Table 5-1. State Parameter Values for Processing Items 


Location Meaning 


STATE.[07:08] This message is received by an application program 
executing the RECEIVE <input header name> 
statement. 


This message is sent by an application program 
executing the SEND <output header name> statement. 


STATE.[13:06] This field contains the index of the first word of the input 
Conversation Area field in the HEADER parameter. 


continued 
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Table 5-1. State Parameter Values for Processing Items (cont.) 


Location Meaning 


STATE.[15:02] The USER_DATA parameter contains the newest 
message data. If a processing item is placing new 
message data into the USER_DATA parameter, then the 
processing item must set STATE.[15:02] to a value of 0 
(zero) to inform the Agenda Processor library that that 
the newest message data are now in the USER_DATA 
parameter. 


The TEXT_1 parameter contains the newest message 
data. If a processing item places new message data into 
the TEXT_1 parameter, then the processing item must 
set STATE.[15:02] to a value of 1 to inform the Agenda 
Processor library that the newest message data are now 
in the TEXT_1 parameter. 


The TEXT_2 parameter contains the newest message 
data. If a processing item places new message data into 
the TEXT_2 parameter, then the processing item must 
set STATE.[15:02] to a value of 2 to inform the Agenda 
Processor library that the newest message date are now 
in the TEXT_2 parameter. 


STATE.[23:08] This field is reserved for use by COMS. 


STATE.[47:24] Processing items use this field to pass information to 
other processing items. COMS initializes this field to a 
value of O (Zero) prior to calling the first processing item. 


Between calls to other processing items, COMS does not 
change the value of STATE.[47:24]. COMS preserves 
the changes made to the message data by one 
processing item until the next processing item is called. 


HEADER Parameter 


The HEADER parameter is an array designed to contain the header passed by the 
program on whose behalf the processing item has been called. When calling a processing 
item, the Agenda Processor library passes to the HEADER parameter a copy of the 
header in the program that is receiving or sending a message. 


The Agenda Processor library passes a copy of the input header when the message has 


yet to be received by the program. The Agenda Processor library passes a copy of the 
output header when the message is being sent by the program. Refer to Section 3, 
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“Communicating with COMS through Direct Windows,” for more information about the 
the input and output headers. 


A processing item can modify fields within the HEADER array so that the HEADER 
contains the correct descriptive information when the processed message is received or 
sent by a program. 


Updating Input Header Fields 


When the HEADER parameter is an input header, you must update the following fields 
of the input header if these conditions apply: 


e The Text Length field of the input header if the processing item changes the length 
of the message data 


e The Conversation Area field of the input header if you wish to pass additional 
information to a program or another processing item 


Updating Output Header Fields 


When the HEADER parameter is an output header, you must update the following fields 
of the output header if these conditions apply: 


e The Text Length field of the output header if the processing item changes the length 
of the message data 


e The Agenda Designator field of the output header if you wish to specify an agenda 
that differs from the agenda originally specified in output header of the application 
program 

e The Destination field of the output header if you wish to specify a destination 
that differs from the destination originally specified in the output header of the 
application program 

e The Conversation Area field of the output header if you wish to pass additional 
information to a program or another processing item 


Refer to Section 3, “Communicating with COMS through Direct Windows,” for 
descriptions of fields within the input and output headers. Refer to the definition of 
the OUTPUT_PROC parameter in this section for more information about specifying 
destinations for processed messages. 


USER_DATA Parameter 
The USER_DATA parameter is an EBCDIC array that can contain the message data 
that is to be preprocessed or postprocessed. When calling a processing item, the Agenda 
Processor library passes in the USER_DATA parameter a pointer to the message data in 


the destination program. 


For a message that is to be postprocessed, do not modify the message data while it is in 
the USER_DATA parameter, because doing this would modify the message area of your 
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program. Moreover, modifying the message data in USER DATA could adversely affect 
subsequent sending of messages and reproducibility during a synchronized recovery. In 
addition, you might need to use the original data more than once to generate multiple — 
messages for the same transaction. 


Move the message data into the TEXT _1 and/or TEXT_2 parameters (described later 
in this section) when you want to modify it. Use the STATE parameter to inform the 
Agenda Processor library as to which parameter contains the newest message data at 
a particular time. When the value of STATE. [15:02] is 0 (zero), the USER_DATA 
parameter contains the newest message data. 


TEXT_1 and TEXT 2 Parameters 


The TEXT _1 and TEXT _ 2 parameters are EBCDIC arrays. You can use these 
parameters as scratch data areas for modifying the message data. 


These parameters each have an initial size of one character. Each must be resized with 
the RESIZE verb prior to being used. A processing item should always check the size 
of the TEXT_1 or TEXT _2 parameter before placing message data into it, because 

the same arrays are reused for each copy of a program that is sending preprocessed 
messages. 


If the processing item changes the length of the message data while it is in the TEXT_1 
or TEXT 2 parameter, you must update the Text Length field in the appropriate header. 
Refer to the definition of the HEADER parameter earlier in this section for more 
information about updating fields in the header. 


The processing item must change the value of STATE.[15:02] if the processing item edits 
or reformats the message data from the USER_DATA parameter toascratch area, or 
from one scratch area to the other. Set STATE.[15:02] to one of the following values to 
let the Agenda Processor library know the new location of the newest message data: 


e Avalue of 1 ifthe TEXT 1 parameter holds the newest message data 
e Avalue of 2 ifthe TEXT 2 parameter holds the newest message data 


OUTPUT PROC Parameter 
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The OUTPUT _PROC parameter is a formal REAL procedure of the Agenda Processor 
library that must be declared in a processing item as follows: 


REAL PROCEDURE OUTPUT_PROC(STATE, 

HEADER, 
TEXT_1, 
TEXT_2); 

REAL STATE; 

ARRAY CD[@]; 

EBCDIC ARRAY TEXT_1[@], TEXT_2[9]; 

FORMAL; 
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When calling a processing item, the Agenda Processor library passes the name of the 
OUTPUT_PROC procedure as a parameter to the processing item. The primary 
purpose of OUTPUT PROC is to generate multiple transactions based on a single 
message that the Agenda Processor library has passed to the processing item. A 
processing item must call OUTPUT PROC multiple times to generate multiple 
transactions. 


You can use OUTPUT_PROC to do the following: 


e Redirect a message to a destination that differs from the destination specified in the 
header that the Agenda Processor library passed to the processing item. To do this, 
modify one of the fields in the header that can specify a destination. 


e Transmit the segments of a segmented message to a single destination. 


e Send a single message to multiple destinations by calling OUTPUT _PROC once for 
each destination. Specify the destinations by creating a header for each destination. 


e Generate multiple messages and send them to a single destination by calling 
OUTPUT_PROC once for each message. 


e Generate multiple messages and send them to multiple destinations by calling 
OUTPUT_PROC once for each message and creating a header to specify each 
destination. 


Refer to “Passing an Input Header to OUTPUT PROC” and “Passing an Output 
Header to OUTPUT_PROC” later in this section for more information about generating 
new transactions by calling OUTPUT_PROC multiple times. Having a program execute 
the SEND statement multiple times is an alternative to having a processing item call 
OUTPUT PROC multiple times. . 


Calling OUTPUT_PROC and Transmitting a Message 


When a processing-item list contains several processing items, you usually wait until the 
last item in the list has completed its tasks before transmitting the completely processed 
message to its destination. There are two ways in which a processing item can transmit a 
message to its destination: 


o- Call OUTPUT_PROC explicitly, passing the parameters described later in “Passing 
the Parameters to OUTPUT PROC.” 


e Allow the Agenda Processor library to transmit the message automatically when the 
last pee item in a processing-item list completes its tasks. 


It is unnecessary to explicitly call OUTPUT_PROC if you are transmitting a single 
message to a single destination, because the Agenda Processor library can do it 

‘automatically. This leaves you free to add, delete, or change the order of the items in a 
processing-item list and be assured that the message will always be transmitted at the 
end of the list. 


Whether a processing item calls OUTPUT_PROC explicitly or allows the Agenda 
Processor library to transmit the message automatically, the message goes to one of the 
following destinations: 
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e The originating station that is specified in the Station field of the input header, if the 


processing item contains an input header in its HEADER parameter. This is the 
most common destination. 


e The station or program that is specified in the Destination field of the output header, 
if the processing item contains an output header in its HEADER parameter. 


e The destination associated with the agenda that is specified in the Agenda 
Designator field of the output header, if the processing item contains an output 
header in its HEADER parameter. 


Passing the Parameters to OUTPUT_PROC 


A processing item must pass the following parameters to OUTPUT_PROC: 


e STATE of type REAL 

e HEADER of type Array 

e TEXT _1 of type EBCDIC Array 
© TEXT 2 of type EBCDIC Array 


The types and semantics of these parameters are the same as for the STATE, HEADER, 
TEXT _1, and TEXT _2 parameters of the PROC_ITEM procedure. You can pass to 
OUTPUT_PROC the same parameters that Agenda Processor library passes to the 
processing item, but you do not have to pass the same parameters. The processing item 
must make all desired modifications to the message data and the input or output header 
before calling OUTPUT _PROC. 


You pass either an input header or an output header to the OUTPUT_PROC procedure, 
depending on whether the message being processed is to be received or sent by an 
application program. You can use OUTPUT_PROC to generate new transactions 

with either an input header or an output header, although different conventions apply, 
depending on which header you are passing. 


Passing an Input Header to OUTPUT_PROC 
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When a processing item passes an input header to OUTPUT PROC, the message can 
be transmitted to a program but not to a station. A precessue item should perform the 
following tasks before calling OUTPUT_PROC: 

e Set STATE. [07:08] toa value of 0 (zero). 


e Set STATE.[13:06] to the index of the first word of the input Conversation Area 
field in the header being passed. 


e Set STATE.[15:02] to a value of either 1 or 2 to indicate which parameter contains 
the newest message data. 
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To allow your program to specify or change a destination when passing an input header, 
choose one of the following methods: 


e Place an agenda designator in the Agenda Designator field of the input header. 
e Place a program designator in the Program Designator field of the input header. 


e Place both an agenda designator and a program designator in the previously 
mentioned fields of the input header. With this method, the program designator 
specifies the destination program, while the agenda designator specifies the 
processing-item list. 


Do not specify an agenda whose destination is INPUT_ROUTER when you want to send 
a message to another program. You must use one of the methods previously described to 
specify the destination program. 


Passing an Output Header to OUTPUT PROC 


When a processing item passes an output header to OUTPUT_PROC, the message can 
be transmitted to a station or a program. A processing item should perform the following 
tasks before calling OUTPUT_PROC: 


Set STATE.[07:08] toa value of 1. 


2. Set STATE. [13:06] to the index of the first word of the output Conversation Area 
field in the header being passed. 


3. Set STATE.[15:02] to a value of 0 (zero), 1, or 2 to indicate which parameter 
contains the newest message data. 


To specify or change a destination when passing an output header, choose one of the 
following methods: . 


e Place an agenda designator in the Agenda Designator field of the output header. 
e Place a program designator in the Destination field of the output header. 


e Place both an agenda designator and a program designator in the Agenda Designator 
and Destination fields of the output header. Using this method, the program 
designator specifies the destination program, while the agenda designator specifies 
the processing-item list. 


If you do not specify a destination in the output header, the Agenda Processor library 
transmits the message to the station or program that originated the current transaction. 
COMS derives the identity of the originator from the input header associated with the 
output header that was passed to the Agenda Processor library. 
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‘Caution 


- When you use a processing item to call OUTPUT_PROC, do not specify a default 


output agenda in the output header of the processing item. This procedure can 
cause the processing item to produce recursive calls that eventually lead to a 
stack overflow. 


Formatting Output Messages 


You can create a processing item that formats or reformats output messages in any way 
you desire before they reach their destinations. However, COMS provides a simple, 
predefined method for specifying or altering carriage control of output messages. 


Altering Carriage Control for Output Messages 


A processing item can specify or alter carriage control for an output message before the 
message reaches its destination, regardless of whether the program or station that sent 
the message has specified carriage control. 


A direct-window program can specify carriage control or allow the COMS default 
setting to be used. A COBOL74 application program can use the BEFORE/AFTER 
ADVANCING option with the SEND statement to specify carriage control, or allow the 
COMS default setting (advancing after one line) to be used. 


Carriage Control Field Values 


A processing item can reset bits [47:16] in the carriage-control field of the output header 
of a direct-window program when the output header is passed to the processing item in 
the HEADER parameter of the PROC_ITEM procedure. 


Table 5-2 describes the possible values you will find in bits [47:16] of the FIELDS word, 
after the direct-window program sends a message and the processing item is called. 
Change the values in bits [47:16] according to your proceeane needs. The default for 
carriage control is 0 (zero). 
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Table 5-2. Carriage Control Field Values 


Meaning 


No line advance. 


A line is advanced before or after the message text is 
written to the output device, depending on the value of 
bit [38:1]. 


No carriage return is done. 


A carriage return is done before or after the message text 
is written to the output device, depending on the value 
of bit [38:1]. 


A new page is required for the output device. 


Bits [37:3] select an action requiring the use of bits 
[47:8] as a parameter. All the actions indicated by bits 
[37:3] are taken before or after sending the message, 
according to the value of bit [38:1]. 


No action is required that uses the value in [47:8] as a 
parameter. 


Bits [47:8] contain a line number. The cursor is set to 
column 1 of this line before or after the message is sent, 
depending on the value of bit [38:1]. 


Bits [47:8] contain the number of lines to be advanced, 

in addition to the number of lines advanced by bit 
_{32:1]. The lines are advanced before or after the 

message is sent, depending on the value of bit [38:1]. 


All interpretation of the carriage control fields should be 
done before the message is sent. 


All interpretation of the carriage control fields should be - 
done after the message is sent. 


continued 
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Table 5-2. Carriage Control Field Values (cont.) 


Meaning 


This bit is currently unused, and must retain the value of 
0 (zero) set by COMS. (The bit might be used by COMS 


in future releases.) 


Contains the number of lines to be advanced. Use of | 
this field depends on bit [37:3]. 


Providing for Processing-Item Results 


5-16 


Prior to the END statement that completes the tasks performed by your processing 
item, include a statement for returning the REAL result of your processing-item 
procedure. The processing item must provide such a result as an instruction to the 
Agenda Processor library regarding the disposition of items in a processing-item list. 


If the processing item does not provide a result, a default value of 0 (zero) is passed 
to the Agenda Processor library. If the processing item calls the OUTPUT_PROC 
procedure, then OUTPUT _PROC could call other processing items. When the last 
processing item called by OUTPUT_PROC completes processing, OUTPUT_PROC 
returns the result of the last processing item to the Agenda Processor library. This 
result is one of the four REAL values described in the following table. 


Table 5-3 contains definitions of the REAL values that a processing item can return in 
the result word. 


Table 5-3. Result Word REAL Values 


Location Meaning 
PROC_ITEM.[07:08] 0 Continue to process other items in the processing-item 
list. . 


Stop processing because there are no more items in the 
processing-item list. 


For a message sent by an application program, a value 

of 1 means that the processing item prematurely 

stopped its processing tasks. In this case, COMS assigns 

a value of 96 to the Status Value field in the output . 
header of the program and returns the newest message 
date to the Agenda Processor library. 


continued 
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Table 5—-3. Result Word REAL Values (cont.) 


Location Meaning 


Stop processing and return the newest message data to 

_ the station that originated it. For a message yet to be 
received by an application program, a value of 2 means 
that COMS is transmitting the newest message data to 
the originating station. 


For a message sent by an application program, a value 
of 2 means that the processing item prematurely 
stopped its processing tasks. In this case, COMS assigns 
a value of 96 to the Status Value field in the output 
header of the program. By examining the conversation 
area, you might be able to determine what caused the 
processing tasks to stop prematurely. 


COMS returns this value only when a processing item 
has explicitly called the OUTPUT_PROC procedure, and 
OUTPUT_PROC has called a processing-item list. If a 
processing item is missing from the list called by 
OUTPUT_PROC, then COMS returns a value of 3 to the 
processing item that originally called OUTPUT_PROC. 


PROC_ITEM.[47:39] This field is reserved for use by COMS. 
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Interactive Recovery 


Interactive recovery applies to application programs that update Data Management 
System IT (DMSII) databases and Semantic Information Manager (SIM) databases 
through direct windows. Recovery through COMS is not supported in the Pascal 
programming language. 


Components of COMS Recovery 
COMS recovery includes the following components: 


e Protected input queues 
e Two-phase transactions 


e Concurrency 


Protected Input Queues 


Protected input queues assure that transactions waiting to be processed by application 
programs are not lost in a halt/load. These input transactions are audited to disk 
when they are received by COMS. All transactions that are not protected are lost in a 
halt/load. ' 


The protected input specification is made in the COMS Utility on an agenda-by-agenda 
basis. For further information on input queue protection, see the COMS Configuration 
Guide. 


Two-Phase Transactions 


Two-phase transactions consist of two phases. In the first phase, all resources are 
locked (no records are freed). In the second phase, all resources are freed by the 
END-TRANSACTION statement. 


All transactions processed by application programs must be two-phase transactions to 
guarantee reproducibility. For further details on two-phase transactions, see “Writing 
Two-Phase Transactions” later in this section. 


Concurrency 


The database attribute “concurrency” implies that in the event of an abort or halt/load 
recovery, all transaction states that have been completed are still reflected in the 
database. No completed transaction states are backed out of the database. Concurrency 
is a feature of a database and does not require intervention by a message control system 
(MCS) to reapply transactions. : se 
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DMSII databases can run with or without concurrency. Concurrency is achieved 

in DMSII by the Data and Structure Definition Language (DASDL) options 
INDEPENDENTTRANS and REAPPLYCOMPLETED. The INDEPENDENTTRANS 
option assures that all transactions processed against the database are two-phase 
transactions. The REAPPLYCOMPLETED option assures that all transactions that 
have completed transaction state are not backed out of a database after an abort or a 
halt/load. 


All transactions processed against DMSII databases that have the. 
INDEPENDENTTRANS option set are by default two-phase transactions. That is, the 
DMSII database software automatically converts a non-two-phase transaction into a 
two-phase transaction with no change to the application programs. 


All transactions processed against DMSII databases that do not have the 
INDEPENDENTTRANS option set must be two-phase transactions. If you do not use 
the INDEPENDENTTRANS and REAPPLYCOMPLETED options, the DMSII database 
does not have concurrency control. 


For more information on the INDEPENDENTTRANS and REAPPLYCOMPLETED 
options, see the A Series DMSII Application Program Interfaces Programming Guide. 


SIM databases always run with concurrency control. This is an integral part of the 
software. Because of the presence of concurrency control in SIM, all transactions 
processed against a SIM database are by default two-phase transactions. For further 
information on SIM, see the InfoExec SIM Technical Overview. 


Preparing to Use Interactive Recovery 


To prepare you for using interactive recovery, the following information is provided: 

e General conventions to follow when writing programs that update a database by 
Means of two-phase transactions 

e COMS actions when a program fails 

e Requirements for a transaction-processing system that updates a database 


e Anoverview of the COMS components that facilitate COMS recovery, and an 
explanation of how recovery works , 
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General Programmatic Conventions 


In writing programs that run under COMS and use interactive recovery, you must use 
the specific programmatic conventions explained in this section. Moreover, you need to 

_ observe the following general programmatic conventions to ensure effective recovery and 
perfect reproducibility: 


e You must group all instructions together into a transaction, so that the program 
enters transaction state using a BEGIN-TRANSACTION statement, performs the 
update activity while in transaction state, and then exits transaction state using an 
END-TRANSACTION statement. 


Caution 


Avoid using SEND and RECEIVE statements during transaction state 
(between a BEGIN-TRANSACTION statement and an END-TRANSACTION 
statement) or you might lose some of the data in your database. 


All transactions that are to be included in interactive recovery, such as the COMS 
header name included in DMS BEGINTRANSACTION and ENDTRANSACTION 
statements, must occur after a RECEIVE statement has been executed. 


e For databases not using the DASDL option INDEPENDENTTRANS, each 
transaction must be a two-phase transaction. In the first phase, the transaction 
should lock records but not free any. In the second phase, the transaction should 
free records but not lock any. In databases with concurrency control, all transactions 
are by default two-phase transactions. 


e For proper recovery of messages after a database abort or program abort, the 
program must first execute a RECEIVE statement to handle the recovery 
transactions and then execute a SEND statement. If aSEND statement is executed 
before a RECEIVE statement, the transactions are not resubmitted. 


Updating by Using Transactions 


All application programs that update an audited database must be restartable, that is, 
able to resume processing where COMS directs them to after an interruption such as an 
abnormal program termination or a system halt/load. 


For databases without concurrency control, DMSIT ABORT/RECOVERY ensures that 

an interruption in processing does not leave the database with partially completed 
transactions. After DMSII ABORT/RECOVERY completes, COMS retrieves information 
from the DMSTI restart data set that points to the last transaction completed by DMSIL. 
Because all transactions completed by COMS are recorded in the COMS transaction 
trail, COMS can resubmit all the transactions that followed the last DMSII-completed 
transaction. COMS resubmits the transactions to the appropriate programs in the 
appropriate order. When the last transaction recorded in the transaction trail is 
successfully reprocessed, COMS recovery is complete. Databases with concurrency 
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control do not encounter aborts. Next, COMS recommences to submit live transactions 
to the database. | 


To perform an update to the database, an application program must place the database 
into the condition called “transaction state.” Transaction state refers to the time during 
which all the updates required for a single transaction are performed. In an application 
program, the BEGIN-TRANSACTION and END-TRANSACTION statements must 
delimit the set of updates to the database that logically compose one transaction. DMSII 
guarantees that either all or none of these updates will appear in the database as the 
result of a database abort. 


When you write update programs for audited databases, think of your updates in terms 
of transactions rather than as arbitrary changes to the database. A transaction is a 
series of changes to the database that constitutes an indivisible, logical change. Write 
each transaction as a group of one or more data-set updates that are performed in one 
transaction-state cycle, causing the program to take the following steps: 


1. Receive a message. 

2. Make all preparations for the update. 
3. Enter transaction state. 
4 


If the program is using a DMSI1-oriented application, perform the update activity, 
which can assign, delete, generate, insert, remove, or store information. If the 
program is using SIM-oriented applications, perform the update activity, which can 
assign, delete, exclude, include, insert, modify, select, or retrieve information. 


5. End transaction state in one of the following ways: 
e Without text. Then send the result to the originator of the transaction. 
e With text that includes an implicit SEND statement. 


6. Return to step 1 (receive another message). 


Your program should perform this sequence once for each update transaction that is to 
be applied to the database. The particular steps the program takes before entering 
transaction state vary, depending upon the application. In applications without 
concurrency, these steps consist of locking or creating records and changing data-item 
values in the work area of the program. 


Every possible action that your program can do in preparation for the update should be 
done prior to entering transaction state. For applications without concurrency, only the 
storing, deleting and other record-update functions must be done during transaction 

state. For all applications, once transaction state is entered, it must not be exited until 
all updates associated with the transaction are performed. Transaction state should be 


_ entered and exited only once per transaction. 


If a program tries to use any of the six update statements when the program is not 

in transaction state, the program is discontinued with an “INVALID OP” error. Ifa . 
program does not follow the sequence of steps listed in this subsection, COMS reports an 
error message to the monitor station. 
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Writing Two-Phase Transactions 


Every database includes a set of assertions, or consistency constraints, that data within 
the database must satisfy. When the data preserve all the constraints, the database 

is said to be consistent; otherwise, the database is said to be inconsistent. To ensure 
that consistency can be achieved in a multiple-program environment, DMSII provides a 
tool known as record-level locking, which allows a process to update a record only after 
retrieving the record with an exclusive lock. Although other processes can concurrently 
retrieve the record, record-level locking protects the record from updating by other 
processes until after it is explicitly or implicitly freed. 


In order for record-level locking to preserve consistency, a programmatic convention 
known as the two-phase transaction must be observed. A transaction is two-phase if it 
can be divided into a locking phase followed by an updating phase. During the locking 
phase, the transaction locks records. During the updating phase, the transaction 

updates records but does not free or lock any. Records are freed automatically at the end 
of the updating phase. 


After the last record is locked and until the first record is updated, the transaction is at 
the mid-transaction point. If two-phase transactions are not used, reproducibility of 


previous results and continued consistency of the database cannot be guaranteed when 
recovery operations complete. 


COMS Actions When a Program Fails 


COMS can take a variety of different actions when a program fails during execution. 
The following explanations show how COMS responds as it encounters different 
statements. The first two lists show the order in which COMS encounters the 
statements for an explicit SEND and an implicit SEND. Following those lists are 

Tables 6-1 and 6-2 that show the points at which COMS can fail and the corresponding 
actions that occur. 


Order of Statements for an Explicit SEND 
RECEIVE 

BEGIN-TRANSACTION with HEADER 
END-TRANSACTION © 


SEND 


8600 0650-000 6-5 


Interactive Recovery 


Order of Statements for an Implicit SEND 


RECEIVE 
BEGIN-TRANSACTION with HEADER 
END~TRANSACTION with Text: SEND 


END TRANSACTION 


Table 6—1. COMS Actions When a Program with an Explicit SEND Fails 


Point in Program Failure Action 


Before a RECEIVE statement starts. No action. Start program when next 
_ transaction is to be delivered. 


After a RECEIVE statement starts, but before Start program and redeliver transaction with 
a BEGIN-TRANSACTION with HEADER a status 93 message. 
statement starts. 


After a BEGIN-TRANSACTION with HEADER Start program and redeliver transaction with 
statement starts, but before the a Status 93 message. 
END-TRANSACTION statement starts. 


After an END-TRANSACTION with HEADER No action. Start program when next 

statement starts, but before the SEND transaction is to be delivered. (This means 

statement starts. — —— that output might be lost because the SEND 
is never done.) 


After a SEND statement starts. No action. Start program when the next 
transaction is to be delivered. 


Table 6-2. COMS Actions When a Program with an Implicit SEND Fails 


Point in Program Failure Action 


Before a RECEIVE statement starts. No action. Start program when next 
transaction is to be delivered. 


After a RECEIVE statement starts, but before Start program and redeliver transaction with 
a BEGIN-TRANSACTION with HEADER a status 93 message. 
statement starts. 


After a BEGIN-TRANSACTION with HEADER Start program and redeliver transaction with 
statement starts, but before an a status 93 message. 

END-TRANSACTION with Text: SEND 

statement starts. 


continued 
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Table 6-2. COMS Actions When a Program with an Implicit SEND Fails (cont.) 


Point in Program Failure - 


After an END-TRANSACTION with Text: Start program and redeliver transaction with 
SEND statement starts, but before an a status 93 message. (This means that 
END-TRANSACTION statement starts. output might get delivered twice. The 


duplicate can be handled by a processing 
item.) 


After an END-TRANSACTION statement No action. Start program when next 
Starts. transaction is to be delivered. 


Note: The ABORT-TRANSACTION statement causes the current 
transaction state to be exited without any updates. COMS does not 
resubmit this transaction. 


Requirements for Using Interactive Recovery 


Torun under COMS and use interactive recovery, a database-processing system must 
include the following: 


e One or more application programs that process transactions 
e One DMSII database or one SIM database 


e IfaDMSII database is used, one restart data set within the DMSII database that 
identifies restart records belonging to COMS 


Possible configurations for data-base-processing systems that use interactive recovery 
include these: 


e One application program that updates one SIM database or one DMSII database 
that is synchronized with COMS 


e Multiple application programs that update one SIM database or one DMSI database 
that is synchronized with COMS 


To use synchronized recovery, you must create a restart data set that stores the data 
needed for recovery. The role played by the restart data set, and instructions for 
creating and using it, are given later in this section. 


Note that COMS does not support modeled databases. For instance, if you have one 
database (DB1), and then develop a new database (DB2) modeled after DB1, COMS 
stores the restart records of DB2 in the restart data set of DB1. This mixing of records 
prevents you from using synchronized recovery. 
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For databases without concurrency control, a DMSII database is synchronized with 
COMS when DMSII and COMS do the following: 


1. DMSII recovery restores the database to the last point in time when no programs 
were in transaction state. 


2. COMS resubmits all committed transactions to their respective application program 
beyond the DMSII recovery point, in the order that they were originally processed 
by multiple programs running asynchronously. 


COMS Components That Facilitate Recovery 


For each database that uses recovery, a COMS internal process called COMS 

Control initiates a separate task called the database (DB) control program. Each DB 

control program initiates a separate DB library. The DB library serves as the data 

communications interface (DCI) library for programs that are controlled by a common 

DB control program. Therefore, the DB control program and the DB library work 

together for each database to support the programmatic interface to GOMS and recovery 
_ operations. 


The transaction processor (TP) library is the DCI library that handles the COMS 
interface to application programs that do not need synchronized recovery. The TP 
library is initiated by COMS Control and does for these application programs what the 
DB control program and the DB library do together for application programs that need 
synchronized recovery. 


Programs associated with the TP library can interface to one or more databases. 
However, COMS does not participate in recovery for these programs. 


How DB Control and the DB Library Work 


The DB control program initiates all application programs that use recovery with a 
particular database. DB control can detect transaction-state aborts that occur while 
your application programs are attempting to update the database. If the DB control 
program does detect an abort, it initiates a recovery cycle and, if necessary, restarts each 
application program. 


In updating the database, application programs receive incoming messages and send 
outgoing messages by calling an entry point known as DCI. This is an entry point of 
the DB library that is associated with a particular DB control program. Ifa database 
recovery is in progress, the program receives a recovery transaction sent by the DB 
library. 


If a program attempts to calla DCI ENTRYPOINT associated with a control stack other 
than its own, the program is discontinued by COMS and an error message is displayed. 


How the Restart Data Set and Transaction Trail Work 


Every DB library has its own transaction trail, which is shared by all the application 
programs assigned to the particular DB library. A transaction trail is a time-ordered, 
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logical audit trail that resides on disk and provides the data for reprocessing database 
transactions in case of a transaction-state abort, system crash, or rollback. A transaction 
trail actually consists of a series of files numbered 1 through N, with 1 being the oldest 
file and N being the newest file. 


When a transaction-trail file is full, COMS closes the file and opens another one, 
incrementing the file number by 1. Alternatively, an operator can use the COMS 
DATABASE < database name> TRAIL CLOSE command to close the current 
transaction trail for a given database and open a new one, whose number is incremented 
by 1. COMS automatically causes a database SYNC point when a transaction trail is 
closed. 


For the multiple-program environment, where preserving the order in which update 
transactions occur is essential to full recovery, COMS provides an efficient way to store 
and use data for reprocessing the transactions in the correct order. COMS stores 
restart information in the transaction trail based on the order of occurrence of the 
END-TRANSACTION statement. 


Bach transaction-trail record contains a copy of the COMS header and message area as 
they appeared in a particular program at the moment that the END-TRANSACTION 
statement was executed for a particular transaction. 


Caution 


Changing the current transaction trail file number on the Database Activity menu 
of the COMS Utility might make recovery of records in existing files impossible. 
Refer to the COMS Configuration Guide for further information. 


The remainder of this section presents the following programming information for 
DMSII databases with and without concurrency and for SIM databases, which always 
include concurrency: 


e Interactive recovery with DMSII databases 
e Interactive recovery with SIM databases 


Interactive Recovery with DMSII Databases 


Interactive recovery with DMSII databases can be used either with or without 
concurrency. Interactive recovery without concurrency is referred to as synchronized 
recovery. Synchronized recovery is a COMS function that resubmits transactions to the 
database application program after a transaction-state abort, system crash, or rollback. 
It is called synchronized recovery because it reprocesses transactions in the same order 
that they were originally processed by multiple programs running asynchronously. The 
recovery process is slightly different, depending on the kind of interruption that has 
occurred. 
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If a transaction state abort occurs, first, DMSII recovery restores the database to the 
last point in time when no programs were in transaction state. Next, COMS resubmits 
all transactions already committed to the database that occurred beyond the DMSII 
recovery point. Last, COMS resubmits all in-process transactions, that is, those 
transactions that have reached the system but have not yet reached the database. If 

a system crash or rollback occurs, the first two steps are the same as in the case of a 
transaction-state abort, but in the third step COMS resubmits all transactions protected 
by input queue protection. 


For information on input queue protection, see the COMS Configuration Guide. For 
information on archive operations, see the COMS Operations Guide. 


To use interactive synchronized recovery, your direct-window program must include 
specific synchronized recovery code, as well as your usual message processing code. This 
section provides general guidelines and specific instructions for using synchronized 
recovery. 


In databases that have concurrency control set, once a transaction has been committed 
to the database, that is, it is past the END-TRANSACTION statement, it is not backed 
out of the database. For example, if three programs are currently in transaction state 
and one of the programs terminates in transaction state, the other two transaction states 
are allowed to complete. The two completed transaction states are not backed out of the 
database. 


This does not mean that these application programs do not need COMS recovery. Three 
recovery situations that require COMS/database synchronization are . 


e Reprocessing an aborted transaction 
e Processing messages held in an input queue of the program 


e Archival recovery 


Reprocessing an Aborted Transaction 
An aborted transaction is a transaction that has not completed successfully, due to 
program termination. COMS resubmits this transaction to the application program with 
an error in the Status field of the input header. For information on appropriate error 
messages, refer to Appendix A. 

Processing Messages Held in the Input Queue of the Program 
After a halt/load and the database has recovered, COMS submits all transactions in the 
application queues. Only those transactions in protected input queues are submitted. 
For information on input queue protection, see the COMS Configuration Guide. 

Archival Recovery 


Archival recovery is the reprocessing of transactions from the transaction trail, typically 
done after a database has been repositioned through a DMSTII rollback. COMS 
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resubmits the transactions to the application in the order the transactions were 
originally processed against the database. 


Refer to “Creating a Restart Data Set” in this section for information about the fields in 
the restart data set that you need to create. Refer to Section 3, “Communicating with 
COMS through Direct Windows,” for information about the COMS input and output 
headers. 


Writing Interactive Recovery Programs Using DMSII 


This subsection provides the programming code for using recovery with DMSII 
databases. A sample of the program flow is presented, highlighting the six subroutines 
necessary for synchronized recovery. There are two possible main loops in the 
interactive recovery program, one with an explicit SEND statement and the other with a 
SEND statement built into the END-TRANSACTION subroutine. Also, note that the 
subroutines INITIALIZE _COMS, BEGIN-TRANSACTION, END-TRANSACTION, 

and EXIT _COMS are different, depending on the release and features you are using. 

To use the features in the current release of DMSII, you need to use the current 

release of COMS. Programs using concurrency control will not encounter aborts. 
Programs without concurrency control might receive resubmitted END-TRANSACTION 
subroutines. 


Creating a Restart Data Set 


In addition to the direct-window program containing synchronized recovery coding, you 
must create a restart data set. When the database administrator defines a database that 
your programs update, he or she must create a restart data set containing three fields 
that are associated with three specific attributes. 


Following is an example of the Data and Structure Definition Language (DASDL) 
description for a restart data set that must be created for each DMSII database updated 
by programs that run under COMS and need synchronized recovery: 


RESTART-DS RESTART DATA SET 
( 
RDS-ID ALPHA(6) COMS-ID; 
RDS-PROG REAL COMS-PROGRAM; 
RDS-LOCATOR REAL COMS-LOCATOR; 
)% 


- These fields of the restart data set are used for the recovery of direct-window programs 
and are maintained by COMS. COMS sets the value of RDS_ID to ONLINE for all the 
transactions generated by direct-window programs. In programs that are not COMS 
programs, such as batch programs, you can use these fields as long as you do not set the 
value of RDS_ID to the value ONLINE. 


You are free to choose any valid DASDL names for the restart data set and the three 
fields in it, but you must do the following: 
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1. Besure that the names in DASDL are the same as the names in your initialization 
routine. 


Use the data types indicated in the example to define each field. 


Identify each field directly to the DASDL compiler and indirectly to COMS by 
including these attributes with exactly these spellings: 


e COMS-ID 
e COMS-PROGRAM 
e COMS-LOCATOR 


4. Ifyou have a spanning set on the restart data set, you must also allow duplicates and 
specify an initial value for the implicit keys in DASDL. 


COMS must create and store a master recovery record in the restart data set of any 
database updated by a COMS transaction processor. If the restart data set contains 

any required items or any other special requirements that COMS cannot satisfy, the 
CREATE and STORE procedures of the master recovery record will fail. This failure 
also can produce negative results on subsequent synchronized recoveries. To prevent 
these potential results, define any specially required items with INITIALVALUE clauses 
in DASDL. 


Using Exception-Condition Statements and DMTERMINATE 


6-12 


Using exception-condition statements in your steps for closing a database is not 
recommended, because your program should terminate abnormally if a database error 

is detected during the database close. If your program does not terminate abnormally 
under these circumstances, recursive aborts of the database could occur. If you must use 
exception-condition statements in your steps for database close, then your program 
should also call DMTERMINATE for those exceptions not specifically handled by your 
program. 


DMTERMINATE is a system-level DMSII procedure that you can invoke at any time 
to display a standard, recognizable error message and to discontinue the application 
program. For information on the syntax in your programming language to call 
DMTERMINATE, see the appropriate language manual. 


Usually, DMTERMINATE should be the last procedure your program calls after it 
checks all other exception conditions that it specifically handles. The DMTERMINATE 
procedure returtis the same values and results that would occur if the program had not 
intercepted the error in the first place—it displays a standard system error message and 
terminates the program. 


DMTERMINATE is not intended as a method of handling common errors such as 
NOTFOUND. It is provided as a way out for programs that encounter unexpected 
errors, such as system errors or I/O errors. 


As a general rule, an application program should go to end of task (EOT) once the 
database that is to be synchronized with COMS is closed. 
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Exceptions on the close of a DMSII database with concurrency control do not affect any 
of the completed transaction states of the interactive application program. By default, 
once a transaction has been committed to the database, it will not be backed out due to 
an abort or a halt/load recovery. 


For DMSII databases with concurrency, the ABORT-TRANSACTION statement can be 
used to discontinue the current transaction state. If this statement is executed by an 
application program, the current transaction will not be resubmitted by COMS. 


For further information about the ABORT-TRANSACTION statement, refer to the 
DMSITI Uiilities Operations Guide. 


Program Flow for Recovery Programs Using DMSII 


Following is an example of the program flow for the declaration and main loop of the 
interactive recovery program using DMSII databases, either with or without concurrency 
control. The program is presented in pseudolanguage, which uses indentation to indicate 
the scope of each statement. 
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| Declaration and Main Program Loop 


KEKKEKREKKERKEKRKEKKEREK 


* DECLARATION PART * 

KREKKEKEKERERKEREKREKEE 
% database must contain restart data set (RDS) % 
% with the ID, PROG, and LOC fields. % 


database DATABASE; 
COMS HEADER CDIN; 
COMS HEADER CDOUT; 
DATA AREA MSG; 


“keto eek RI 


* MAIN LOOP * 


KEKEREKEKKEREEK 


INITIALIZE _COMS; 
% main loop with explicit send % 
WHILE CDIN.STATUS NOT = 99 DO 
RECEIVE CDIN INTO MSG; 
IF CDIN.STATUS NOT = 99 THEN 
PREPARE MSG; % your message-processing code % 
BEGIN-TRANSACTION CDIN NO-AUDIT; 
UPDATE_DATABASE; 
END-TRANSACTION CDOUT AUDIT RDS; 
SEND CDOUT FROM MSG; 
% or main loop with send built into end transaction % 
WHILE CDIN.STATUS NOT = 99 DO 
RECEIVE CDIN INTO MSG; 
IF CDIN.STATUS NOT = 99 THEN 
PREPARE_MSG; % your message-processing code % 
BEGIN-TRANSACTION CDIN NO-AUDIT; 
UPDATE_DATABASE; 


END-TRANSACTION CDOUT USING MSG AUDIT RDS; 
EXIT_COMS; 
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Subroutines Using COMS and DMSII (No RDS STORE) 


If you have the current release of COMS and of DMSII and do not use the DASDL 
option RDS STORE, use the following subroutines for the main loop of your interactive 
recovery program: . 


KRRERKEKEKRKKKEREEKKER 


* INITIALIZE _COMS * 


KEKKKKRERKEKKKERERKEE 


OPEN UPDATE DATABASE 
ON EXCEPTION 
DMTERMINATE; 
ESTABLISH COMS LINK; 
ENABLE INPUT COMS "ONLINE" 


CREATE RDS; % required 
MOVE "ONLINE" TO RDS.ID; % required 


MOVE CDIN.PROGRAMDESG TO RDS.PROG; % required 
% MOVE CDIN.RESTARTLOC TO RDS.LOC; % no longer required 


KEKEKRERKEKEREEREKEREKRRKREEREREKKRRERERRKRERRRRERERE 


* BEGIN TRANSACTION TIME (without concurrency) * 


KKKKKEKEKKEKERERRKEKRKEKRERERKERRREEEREKERERKRERRREREK 


BEGIN-TRANSACTION CDIN NO-AUDIT 
ON EXCEPTION 

IF ABORT THEN % not with INDEPENDENTTRANS option 
GO_RECEIVE_TRANSACTION . 

ELSE IF AUDITERROR THEN % program logic error 
DMTERMINATE % already in transaction state 

ELSE IF DEADLOCK THEN 
GO_RECEIVE TRANSACTION 

ELSE DMTERMINATE3 % should not happen 


KREKKKKEKRKERKEKKEKEREEKEEEKREEERERERKREEKEKRRREKERER 


* BEGIN TRANSACTION TIME (with concurrency) * 


KKEKEKKEKKKEKEREKRERKKEERREEKKEKKRKRERKEEREEKERERERERE 


BEGIN-TRANSACTION CDIN NO-AUDIT RDS 
ON EXCEPTION 
IF AUDITERROR THEN % 
DMTERMINATE % 
ELSE -IF DEADLOCK THEN 
GO_RECEIVE_TRANSACTION 
ELSE DMTERMINATES % should not happen 


program logic error 
already in transaction state 
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KKKEKEKKRKEREKRERKREKRKERRKRERKRERREKRRKEREERERERREE 


* END TRANSACTION TIME (without concurrency) * 


KKKKRKKKEKEKREKEREKEKEKRE KEKE ERE RERRRREEREREEE 


END-TRANSACTION CDOUT AUDIT RDS 
ON EXCEPTION 


IF ABORT OR DEADLOCK THEN % no abort with INDEPENDENTTRANS 


GO_RECEIVE TRANSACTION | 


ELSE IF AUDITERROR THEN program logic error 


oe of 


DMTERMINATE not in transaction state 
ELSE IF DATAERROR THEN 

DMTERMINATE | 
ELSE DMTERMINATE; % should not happen 


KKREKEKKEKREEKERKRKRKERERKEERKREREKEREREKRERKKREEEE 


* END TRANSACTION TIME (with concurrency) * 


KREKEKEKEKRKRKEKEKEEREEREREKRREKRERERRERREERKRKRKEEEE 


END-TRANSACTION CDOUT AUDIT RDS 
ON EXCEPTION 


IF AUDITERROR THEN % program logic error _ 

- DMTERMINATE % not in transaction state 
ELSE IF DATAERROR THEN 

DMTERMINATE 
ELSE DMTERMINATE; % should not happen 


RAEKKEEKKEEKEKER 


* EXIT_COMS * 


KREKKERKKEREEKKE 


%.RDS handling no longer required % 


CLOSE DATABASE; 

IF DB CLOSE ERROR THEN 
DMTERMINATE3$ 

EXIT PROGRAM; 
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Subroutines Using COMS and DMSII (RDS STORE) 


If you have the current release of DMSII and of COMS and your database uses the 
DASDL option RDS STORE, use the following program flow for interactive recovery. 
This program includes the RECREATE RDS option after the ABORT or DEADLOCK 
exception in both the BEGIN-TRANSACTION and END-TRANSACTION statements. 


KEKKEKKKEKEREEKKEEEERE 


* INITIALIZE COMS * 


KKEKKERKREEREREREKREEEKE 


OPEN UPDATE DATABASE 
ON EXCEPTION 
DMTERMINATE3$ 

ESTABLISH COMS LINK; 
ENABLE INPUT COMS "ONLINE" 

CREATE RDS;_ % required 

MOVE "ONLINE" TO RDS.ID3 required 

MOVE CDIN.PROGRAMDESG TO RDS.PROG; % required 
% MOVE CDIN.RESTARTLOC TO RDS.LOC;} % no longer required 


oe 


KKREKEKKEKKEKKEKKKEKKERKEERERREREREKEEKKEKRERERREKRRRKEREKREE 


* BEGIN TRANSACTION TIME (without concurrency) * 


KKKERKREKRKKRKERREKKERKEREREREREEKEKRREERERKKRERRKRERER 


BEGIN-TRANSACTION CDIN NO-AUDIT 
ON EXCEPTION 

IF ABORT THEN % not with INDEPENDENTTRANS option 
RECREATE RDS; % unique for RDS STORE case 
GO_RECEIVE_TRANSACTION; 

ELSE IF AUDITERROR THEN % program logic error 
DMTERMINATE % already in transaction state 

ELSE IF DEADLOCK THEN 
GO_RECEIVE_TRANSACTION 

ELSE DMTERMINATES$ % should not happen 


KEKKEERKREKKEKKEKKEEEEREREREREREKRERRRREEERERKREREERE 


* BEGIN TRANSACTION TIME (with concurrency) * 


KEKKKKEKEEKERKERKEERERREREREKREREREKEEREEREREEE 


BEGIN-TRANSACTION CDIN NO-AUDIT 
ON EXCEPTION 
IF AUDITERROR THEN % program logic error _ 
DMTERMINATE % already in transaction state 
ELSE IF DEADLOCK THEN 
GO_RECEIVE_TRANSACTION 
ELSE DMTERMINATE$ % should not happen 
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KKEKEKEEEKKKEREREREEEERRERERERRERRRERERRREKEEEE 


* END TRANSACTION TIME (without concurrency) * 


KKKKKEKEKEKKKEKERKRREERRERKRERKEKKEREEREREREREKREKERER 


END-TRANSACTION CDOUT AUDIT RDS 
ON EXCEPTION 
IF ABORT OR DEADLOCK THEN % no abort with INDEPENDENTTRANS 
: option 
RECREATE RDS; % unique for RDS STORE case 
GO_RECEIVE TRANSACTION; 
ELSE IF AUDITERROR THEN 4% program logic error 
% oN 


DMTERMINATE % not in transaction state 
ELSE IF DATAERROR THEN 

DMTERMINATE 
ELSE DMTERMINATE; % should not happen 


KREKKKREKRKEKEERKEREEKKREKRREKREEREERREKEKRERKREER 


* END TRANSACTION TIME (with concurrency) * 


KRKKKKERKERKEKREEERKRERREREKRERREEERREREEERERRERE 


END-TRANSACTION CDOUT AUDIT RDS 
ON EXCEPTION 
IF DEADLOCK THEN © 
RECREATE RDS; % 
GO_RECEIVE_TRANSACTION; 
ELSE IF AUDITERROR THEN % program logic error 
Nn 


unique for RDS STORE case 


DMTERMINATE % not in transaction state 
ELSE IF DATAERROR THEN 

DMTERMINATE 
ELSE DMTERMINATE3$ % should not happen 


KEKKEKEEEEREKR 


* EXIT_COMS * 


KKKKKKKKRKERE 


% RDS handling no longer required % 


CLOSE DATABASE; 

IF DB_CLOSE_ERROR THEN 
DMTERMINATE; 

EXIT PROGRAM; 
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Interactive Recovery Programs with SIM Databases 


This subsection provides the program code for using COMS recovery with SIM 
databases. 


A sample of the program flow is presented, highlighting the six subroutines necessary for 
COMS/SIM recovery. There are two possible main loops in the recovery program, one 
with an explicit SEND statement and the other with a SEND statement built into the 
END-TRANSACTION subroutine. 


Using Exception-Condition Statements 


As a general rule, an application program should go to end of task (EOT) once the 
database that is to be synchronized with COMS is closed. Exceptions on the close of a 
DMSII database with concurrency control do not affect any of the completed transaction 
states of the interactive application program. By default, once a transaction state has 
been committed to the database, it is not backed out due to an abort or a halt/load 
recovery. 


You can use the ABORT-TRANSACTION statement to discontinue the current 
transaction state. If this statement is executed by an application program, the current 
transaction is not resubmitted by COMS. 


For information about error messages on program termination, or about the 
ABORT-TRANSACTION statement, see the DMSITI Utilities Operations Guide. 


Declaration and Main Program Loop 


Following is an example of the program flow for the declaration and main loop of a 
COMS/SIM recovery program. The program is presented in pseudolanguage, which uses 
indentation to indicate the scope of each statement. 


KREKEKKRERKKRREKRKEKER 


* DECLARATION PART * 


KKREKRKRKEKKEREEKERREREK 


SEMANTIC database DATABASE; 
COMS HEADER CDIN; 

COMS HEADER CDOUT; 

DATA AREA MSG; 
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KREKKKREEKREEKREE 


* MAIN LOOP * 


KAKKKKEKEKKEREEK 


INITIALIZE_COMS; 
% main loop with explicit send % 
WHILE CDIN.STATUS NOT = 99 DO 
RECEIVE CDIN INTO MSG; 
IF CDIN.STATUS NOT = 99 THEN 
_ PREPARE_MSG; % your message-processing code % 
BEGIN-TRANSACTION; 
UPDATE_DATABASE; 
END-TRANSACTION CDOUT; 
SEND CDOUT FROM MSG; 
% or main loop with send built into end transaction % 
WHILE CDIN.STATUS NOT = 99 DO 
RECEIVE CDIN INTO MSG; 
IF CDIN.STATUS NOT = 99 THEN 
PREPARE_MSG; % your message-processing code % 
BEGIN-TRANSACTION; 
UPDATE_DATABASE; 
END-TRANSACTION CDOUT; 
EXIT_COMS; 
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Batch Recovery 


This section describes a programming method for processing batch input in database 
applications. Batch recovery through COMS is not supported in the Pascal programming 
language. 


You can use batch programs to process a set of transactions without continually 
interacting with the terminal. At any time, a batch program can be initiated by an 
interactive transaction. The method of batch programming described in this section 
allows batch processing and online processing to take place simultaneously. This method 
also ensures the following: 


e The batch job will be synchronized with online transactions. 


e Recovery can be performed. 


This method of batch programming requires all batch transactions to be invoked by an 
incoming online transaction from a terminal or another program. All programs must be 
run through COMS direct windows. 


Before you begin the procedures in this section, read the descriptions of the 
Conversation Area field of the input and output headers in Section 3, “Communicating 
with COMS through Direct Windows.” 


Recovery Considerations 


Batch recovery procedures require each transaction to be synchronized with the 
COMS-generated transaction trail for the database. Your batch program must retain 
enough information to know where to restart processing after database recovery and 
COMS recovery complete. 


For example, in a case in which you are using a batch file, this information might include 
the batch file name and the actual key of the record that causes the update to be 
performed. 


Input to batch transactions can take one of three forms: the input transactions that 
initiated the program; input transactions read from a tape, disk file, or database; and 
transactions that are resubmitted during recovery. . 


To synchronize recovery between online programs and batch programs, the batch 
programs must identify to COMS each transaction being performed. This is 
accomplished by using the BEGIN-TRANSACTION WITH option, which allows COMS 
to audit the input transaction on the transaction trail. In the event of a recovery, COMS 
can then reprocess the online and batch transactions in the original order. 
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One way to retain the information needed for recovery is to place that information in 
the Conversation Area field of the input header before the program enters transaction 
state. This information is used during recovery to determine which file and record the 
last processed transaction came from and, thus, where to continue processing in the | 
batch file. If the application is using a DMSII database, the information regarding batch 
recovery should be duplicated in the restart data set record. If the application is using 
a SIM database, the information regarding batch recovery should be duplicated in the 
restart class. For information on classes, see the InfoExec SIM Technical Overview. 


Data to be saved in the input header must be placed in the Conversation Area field 
before executing a BEGIN-TRANSACTION statement. For batch programs, it is 
sufficient to save the file name and the record number. The program can also place a 
copy of the record in the message variable specified by the BEGIN-TRANSACTION 


statement. If this were done during recovery, the program would not require the input 


file to be available. This is an important operational consideration for sites that require 
archival recovery. | | 


Recovery data must also be saved in the database. This is necessary for those cases in 
which COMS does not resubmit transactions to the batch application after a halt/load 
(that is, no transactions for this batch program have been rolled off the database). The 
program must be able to restart from the information in the database. Therefore, the 
batch program must also store in the database the restart information saved in the 
Conversation Area field. 


For every BEGIN-TRANSACTION and END-TRANSACTION statement, COMS 
needs to be notified so that it can put the information into its transaction trail. 
This requires COMS application programs that have enabled batch mode to use 
the BEGIN-TRANSACTION statement that identifies the message variable. This 
information is used for ordering and recovery purposes. 


During recovery, in each resubmitted transaction (that is, each transaction for which 

the Status field of the input header contains the value 92), the header and message 

area appear as they did at the begin-transaction point when the transaction was 

first processed. As a result, the batch file and record location that you placed in the 
Conversation Area field of the input header when processing the record the first time are 
resubmitted along with the message variable. 


The following are the results produced by a batch transaction failure: 


e Batch transaction failure during transaction state 


When a batch transaction repeatedly fails after the mid-transaction point, it is 
resubmitted with a value of 90 in the Status Value field of the input header. 


If a batch program receives a value of 90 for a transaction, do not allow the program 
to process the transaction, because that transaction caused the original series of 
aborts. . . 


e Batch transaction failure after transaction state 


When a batch transaction repeatedly fails after a transaction occurs, it is 
resubmitted with a value of 80 in the Status Value field of the input header. 
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If a batch program receives a value of 80 for a transaction, do not allow the program 
to restart a transaction immediately, because the completion of that transaction 
initially caused the program repeated failures. 


After the begin-transaction point, the message area and relevant portions of the header 
should appear the same regardless of whether the program is in normal or recovery 
mode. Therefore, the programming steps that you take after this point do not need to 
differentiate recovery transactions from normal transactions. 


For additional information on the restart data set and recovery, refer to Section 6, 
“Interactive Recovery.” 


Programming for batch recovery differs, depending on whether or not your database has 
concurrency control. The remainder of this section presents programming information in 
the following subsections: 


e Writing programs using batch recovery without concurrency 


e Writing programs using batch recovery with concurrency 


Writing Programs Using Batch Recovery without 
Concurrency 


This subsection provides the program flow and subroutines for programs that use batch 
synchronized recovery. These are programs that access DMSII databases without 
concurrency. The examples are presented in pseudolanguage. 


A COMS batch program is initiated by an interactive transaction. This transaction can 
be received only while a program is in interactive mode. The batch recovery program 
first initializes batch mode to receive and process any transaction being recovered due to 
a halt/load. It then changes to interactive mode to receive the transaction that initiated 
the batch program. The program then switches to batch mode to process the batch data. 
Finally, the batch program switches back to interactive mode to receive either another 
interactive transaction or the COMS notification to go to end of task. © 


In batch mode, the program does its processing until it gets an abort on a DMSII 
statement. In response to the abort, the program has to receive the transactions that 
were backed out by the database abort and reapply them to the database. This is done 
while the program is still in batch mode. The transactions are identical copies of what 
the program gave to COMS at the begin-transaction point in the message area. They 
must provide enough information to simulate the original database update. 


When the recovery is complete, the program restarts its batch processing, continuing 
where it left off. The restart data set and/or the Conversation Area field of the input 
header must provide enough information for the program to determine the restart 
location for the batch process. Examples of the necessary information are file title and 
record number if the program reads a disk file as input to the database, or a unique key 
into the data set if the program scans through the database. When all the batch work is 
done, the program goes back into interactive mode to receive either a new transaction or 
the COMS notification to go to end of task. 
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Application recovery data must be stored in both the Conversation Area field of the 
input header and the restart data set. Upon resubmission of messages, the application 
program uses the recovery data stored in the Conversation Area field when the 
transaction was originally processed. When a halt/load occurs, a transaction must have 
been backed out of the database to be resubmitted by COMS. The application uses the 
recovery data in the restart data set. 


At initialization, the program can be in one of two operation modes. It might have been 
brought into the mix because a new transaction was given to it. It might have been 
restarted because it was running earlier and it aborted, the system halt/loaded, or the 
database was rolled back for archival recovery. If the program was restarted, it does 
not receive its initial transaction, but receives only the transactions supplied with the 
BEGIN-TRANSACTION statement. 


Declaration and Main Program Loop 


Your program should start by declaring its database, headers, and data message area. 
When it moves to the main loop, it should initialize the COMS interface and then handle 
any recovery of batch processing that had not been completed. When it has finished 
running any interrupted processing, the program should then handle any online input 
from COMS that submits new batch runs, or it should terminate. Following is the 
program flow for the declaration and main loop of the batch synchronized recovery 
program. The examples are presented in pseudolanguage, which uses indentation to 
indicate the scope of each statement. 


KEKERRREERREREREKKEEEE 


* DECLARATION PART * 


KREKKKRRKERRERRRERERER 


database DATABASE; 
COMS HEADER CDIN; 
COMS HEADER CDOUT; 
DATA AREA MSG; 


KEKEKKEKKEKRKEKK 


* MAIN LOOP * 


KREKKKKKKRKKKKK 


INITIALIZE_COMS; 
IF MY_BATCH_RESTARTED THEN 

DO_BATCH_PROCESSING; 

INITIALIZE_ONLINE_MODE 
WHILE CDIN.STATUS NOT = 99 DO 

RECEIVE CDIN INTO MSG; 

IF CDIN.STATUS NOT = 99 THEN 
INITIALIZE_BATCH_MODE; 
DO_BATCH_PROCESSING; 

-INITIALIZE_ONLINE_MODE; 

EXIT_COMS; 
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Initializing COMS 


This step of the batch synchronized recovery program should open the database to be 
updated, establish a link to COMS, and initialize the restart data set. It should also find 
the restart data set record for this program. For more information on initialization, 

see Section 3, “Communicating with. COMS through Direct Windows.” For more 
information on the restart data set, see Section 6, “Interactive Recovery.” 


Following is the program flow for the initialization step of the batch synchronized 
recovery program: 
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KKRKEKKREKEKREERKEKKRKEEEER 


* INITIALIZE _COMS * 


KAKEKKKERKEKKKKERKKEEK 


OPEN UPDATE DATABASE 

ON EXCEPTION 

DMTERMINATE; 

ESTABLISH COMS LINK; 
ENABLE INPUT COMS "BATCH"; 
RESET MY_BATCH_RESTARTED3; 
The program has just come up. It must check to see if any 
of its transactions have been rolled back. If transactions have 
been rolled back, then COMS resubmits them from the 
transaction trail. The CONVERSATION AREA 
of such a resubmitted message can include the 
data necessary to simulate the database update. 


oe 


w & & & & 


RECEIVE CDIN INTO MSG 

NO DATA 

RECEIVE FOUND RECOVERY MESSAGE 

ELSE | 

SET FOUND _RECOVERY_MESSAGE % COMS is resubmitting transactions 
that were rolled back. _ 
After the resubmissions are 
complete, the remaining 
batch transactions 
must be completed. 


SET MY_BATCH_RESTARTED; 


v d& & de 
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% COMS might not have transactions to resubmit, but the batch update 
% might have been incomplete during the last run. The program must 
% check the RESTART DATA SET now. | 
LOCK RDS AT RDS.ID = "ONLINE" AND % Note: ONLINE not BATCH. 
RDS.PROG = CDIN.PROGRAMDESG 
ON EXCEPTION 


IF NOTFOUND THEN % No recovery need be done. 
CREATE RDS % RDS area is created for later use. 
The following code is no longer required. 
MOVE "ONLINE" TO RDS.ID 


MOVE CDIN.PROGRAMDESG TO RDS.PROG 
s MOVE CDIN.RESTARTLOC TO RDS.LOC 
PLACE_USERDATA_IN_RESTART_REC 


se oe oe oe 


ELSE 
DMTERMINATE Some other DMERROR. 
ELSE Last run was incomplete. 


SET MY_BATCH_RESTARTED; % The remaining batch transactions 
must be completed. 


Finish all resubmitted transactions. 


Ho 3 3 d & 


IF FOUND RECOVERY MESSAGE THEN 
DO_INITIAL_BATCH RECOVERY; 


Initializing Interactive Mode 
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Interactive mode allows a program to receive nonrecovery transactions, and to 


_ be signaled when to go to end of job (EOJ). It deletes an eventual batch mode 


restart-data-set record. It reinitializes the restart data set to contain the interactive 
designator of the program and informs COMS about the mode change. 


Following is the program flow for initializing the interactive mode in the batch 
synchronized recovery program: 


KEKKKKKEKEKEEEKERERERRRRERERRERERKE 


* INITIALIZE_INTERACTIVE_MODE * 


KKREKKERREKEKKERKERKERKRERERERERE 


BEGIN-TRANSACTION CDIN NO-AUDIT RDS; 
LOCK RDS AT RDS.ID = RDS.ID AND RDS.PROG = RDS.PROG 
ON EXCEPTION 
IF NOT FOUND THEN 
RECREATE RDS; 
INITIALIZE RDS.MYRESTARTINFOs 
ELSE DMTERMINATE 
ELSE 
DELETE RDS; 
ENABLE INPUT CDIN "ONLINE" $ 
END-TRANSACTION AUDIT RDS; 
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Initializing Batch Mode 


Initializing batch mode allows your program to receive only recovery transactions. This 
program subroutine also informs COMS of the switch from interactive to batch mode. 
Following is the program flow for initializing batch mode within your batch synchronized 
recovery program: 


KEKEKKKEKERKKRKREKRKEKRKREKKKEEE 


* INITIALIZE BATCH MODE * 


KEKEEKKEREEKREKKEREERKERE 


ENABLE INPUT CDIN "BATCH"$ 


Initial Batch Recovery 


You can use the batch recovery subroutine to allow your program to participate in 
the COMS synchronized/archival recovery when it receives a recovery transaction in 
INITIALIZE _COMS. This subroutine receives recovery transactions and updates a 
database. 


Following is the program flow for doing initial batch recovery within the batch 
synchronized recovery program: 


KKEKEKEEKEKKRKEKREKRERKERRKEKREEREKRE 


* DO_INITIAL_BATCH RECOVERY * 


KEEKKEKKRKRKEREKEREREKRKEREREREKK 


RESET NO_MORE_RECOVERY 
WHILE NOT NO MORE RECOVERY DO 
HANDLE_RECOVERY_TRANSACTION; 
RECEIVE CDIN INTO MSG 
NO DATA | 
SET NO_MORE_RECOVERY; 


Abort Batch Recovery 


Use this subroutine to allow your program to participate in synchronized or archival 
recovery when it discovers a database abort. The subroutine receives recovery 
transactions and updates the database. 
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Following is the program flow for doing abort batch recovery within the batch 
synchronized recovery program: 


KRKKKEKEKEKKREKREKKEKKRRREKREERE 


* DO_ABORT_BATCH RECOVERY * 


RERKERERERKEKEKRKEKRKEEREREKRAERE 


RESET NO_MORE_RECOVERY 
bo 
| RECEIVE CDIN INTO MSG 
NO DATA 
SET NO_MORE_RECOVERY 
ELSE 
HANDLE_RECOVERY_ TRANSACTION 
UNTIL NO_MORE_RECOVERY; 


Handling the Recovery Transaction 


Following is the subroutine for handling the recovery transaction within the batch 
synchronized recovery program: 


KREKKKEERERRKRKERRERREEREKRRERREE 


* HANDLE RECOVERY_TRANSACTION * 


KEKEKKKKKERKEKRKEKERKERERRERREEKEER 


SIMULATE_ORIGINAL_TRANSACTION; 

MOVE MY_RESTARTINFO TO CDIN.CONVERSATION.RESTARTINFO; 
BEGIN-TRANSACTION CDIN USING MSG NO-AUDIT RDS; 
UPDATE_DATABASE; 

MOVE MY_RESTARTINFO TO RDS.RESTARTINFO; 
END-TRANSACTION CDOUT AUDIT RDS; 


Batch Processing 


You use the batch processing subroutine to update a database until an abort is detected 
or the processing is done. This subroutine stores restart information necessary to 
identify where to continue for recovery. This is done in both the transaction trail (using 
the Conversation Area field of the input header) and in the restart data set. _ 
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| Batch Recovery | 


Following is the program flow for batch processing within the batch synchronized 
recovery program: 


KREKKKEKKREKRERKEEKRERREEKEK 


* DO BATCH _PROCESSING * 


KEKKKKKEKEKEREEKEREREEKREEEKEA 


DO 
MOVE MY_RESTARTINFO TO RDS.RESTARTINFO; 
MOVE MY_RESTARTINFO TO CDIN.CONVERSATION.RESTARTINFO; 
BEGIN-TRANSACTION CDIN USING MSG NO AUDIT RDS; 
UPDATE_DATABASE; 
END-TRANSACTION CDOUT AUDIT RDS; 

UNTIL ALL_WORK_DONE3; 


COMS and DMSII (No RDS STORE) 


If you have COMS and DMSII and do not use the RDS STORE option, use the following 
program flow for batch processing: 


KAKKKEKRKEKEEKRRKEREEKEERREEKRE 


* BEGIN TRANSACTION TIME * 


KEKEKKEKKERERRREEKRERERKREEKEE 


BEGIN-TRANSACTION CDIN NO-AUDIT USING MSG 
ON EXCEPTION 

IF ABORT THEN 
GO_DO_BATCH_RECOVERY 

ELSE IF AUDITERROR THEN % program logic error 
DMTERMINATE % already in transaction state 

ELSE IF DEADLOCK THEN 
GO_DO_BATCH_RECOVERY 

ELSE DMTERMINATE$ % should not happen 


oe 


not with INDEPENDENTTRANS option 


KEKKKKKEKERERKRKKERRERREREE 


* END TRANSACTION TIME * 


KKEREKKRKKREERKRRERRREREREE 


END-TRANSACTION CDOUT AUDIT RDS 
ON EXCEPTION 
IF ABORT OR DEADLOCK THEN % no abort with INDEPENDENTTRANS 
option 
GO_DO_BATCH_RECOVERY 


ELSE IF AUDITERROR THEN program logic error 


oe 


DMTERMINATE not in transaction state 
ELSE IF DATAERROR THEN 

DMTERMINATE . 
ELSE DMTERMINATE$ % should not happen 
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COMS and DMSII (RDS STORE) 


If you have the current release of DMSII and of COMS and your program uses the 
DASDL option RDS STORE, use the following program flow for batch processing (note 
the RECREATE RDS option after the ABORT exception in the BEGIN-TRANSACTION | 
statement and after the ABORT or DEADLOCK exception in the END-TRANSACTION 


statement): 


KEEKKKERKKEKEREKEKRKEERERRERKE 


* BEGIN TRANSACTION TIME * 


KEEKKRKREKKEKKRREEKRRKEREKREKER 


BEGIN-TRANSACTION CDIN NO-AUDIT USING MSG 


ON EXCEPTION 

IF ABORT THEN 
RECREATE RDS; 
GO_DO_BATCH_RECOVERY 

ELSE IF AUDITERROR THEN % 
DMTERMINATE 

ELSE IF DEADLOCK THEN 
GO_DO BATCH RECOVERY 

ELSE DMTERMINATE; 


Xe & 


% 


% 


KRXRKRKERKKEERREEEKEREEREE 


* END TRANSACTION TIME * 


KRKEKKKKRKEKRKREKRREERRERKERRER 


END-TRANSACTION CDOUT AUDIT RDS 
ON EXCEPTION 
IF ABORT OR DEADLOCK THEN 


RECREATE RDS; 
GO_DO BATCH RECOVERY; 
ELSE IF AUDITERROR THEN 
DMTERMINATE 
ELSE IF DATAERROR THEN 
DMTERMINATE 
ELSE DMTERMINATES$ 
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not with INDEPENDENTTRANS option 
unique for RDS STORE case 


program logic error 
already in transaction state 


should not happen 


9 
6% 


no abort with INDEPENDENTTRANS 
option 


unique for RDS STORE case 


ON 


program logic error 
not in transaction state 


we & 


se 


C) 


should not happen 
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Exiting COMS 


Use the following subroutine to exit COMS whether or not your program uses the 
DASDL RDS STORE option: 


KRKEKKKKKKKKKEK 


* EXIT_COMS * (Database with or without RDS STORE) 


KRKKKEKKEEKEK 


% RDS handling no longer required if coming out of online mode % 


CLOSE DATABASE; 

IF DB_CLOSE_ERROR THEN 
DMTERMINATE; 

EXIT PROGRAM; 


Writing Programs Using Batch Recovery with 
Concurrency | = 


This section provides the program flow and subroutines for programs that use batch 
recovery. These are programs that access DMSII databases with concurrency, 
or programs that access SIM databases. These databases do not need additional 


synchronized recovery programming. 


A COMS batch program is initiated by an interactive transaction. This transaction can 
be received only while a program is in interactive mode. The batch recovery program 
first initializes batch mode to receive and process any transaction being recovered due to 
a halt/load. It then changes to interactive mode to receive the transaction that initiated 

. the batch program. 


The program then switches to batch mode to process the batch data. Finally, the 
batch program switches back to interactive mode to receive either another interactive 
transaction or the COMS notification to go to end of task (KOT). 


At initialization, the program can be in one of two operation modes. It might have been 
brought into the mix because a new transaction was given to it. If the program was 
restarted, it does not receive its initial transaction, but does receive only the transactions 
supplied with the BEGIN-TRANSACTION statement. It might have been restarted 
because it was running earlier and it aborted, because of a system halt/load, or because 
the database was rolled back for archival recovery. 


Application recovery data must be stored both in the Conversation Area field of the input 
header and in the restart class. Upon resubmission of messages, the application program 
uses the recovery data stored in the Conversation Area field when the transaction was 
originally processed. When a halt/load occurs, no transaction is resubmitted by COMS 

if it has not been backed out of the database. If no transaction is resubmitted to the 
batch application program, but there is recovery data in the restart class, the application 
program must start reprocessing from the data in the restart class. 
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Batch Recovery 


If the program faults and gets terminated abnormally, COMS automatically restarts the 
program. After enabling the BATCH option, the program must receive the transaction 
that caused it to fault. This transaction has a status code of 90. Do not reprocess the 
transaction, but rather evaluate the error message that is returned. The transaction is 
an identical copy of what the program gave to COMS at the begin-transaction point in 
the message area. 


Once the transaction that caused the abort is processed, the program restarts its 
batch processing, continuing where it left off. The restart class has to contain enough 
information to allow the program to find where in the batch process to restart. For 
information on classes, see the InfoExec SIM Technical Overview. 


Examples of the necessary information are file title and record number if the program 
reads a disk file as input to the database, or a unique key into the data set if the program 
scans through the database. When all the batch work is done, the program goes back 
into interactive mode to receive either a new transaction or the COMS notification to go 
to end of task. 


Declaration and Main Program Loop 
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Your program should start by declaring its database, headers, and data message area. 
When it moves to the main loop, it should initialize the COMS interface and then handle 
any recovery of batch processing that had not been completed. When it has finished 
running any interrupted processing, the program should then handle any online input 
from COMS that submits new batch runs, or it should terminate. 


Following is the program flow for the declaration and main loop of the batch recovery 


program. The program is presented in pseudolanguage, which uses indentation to 
indicate the scope of each statement. 
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KEKKKKKEKRKKEEREKREREEEE 


* DECLARATION PART * 


KEKKKKKKEREREKKEREKER 


database DATABASE; 
COMS HEADER CDIN; 
COMS HEADER CDOUT; 
DATA AREA MSG; 


KEKKKKKKKEKKKEK 


* MAIN LOOP * 


KEKRKKEKKEREKEER 


INITIALIZE_COMS; 
IF MY BATCH RESTARTED THEN 
DO_BATCH_PROCESSING; 
INITIALIZE_ONLINE MODE 
WHILE CDIN.STATUS NOT = 99 DO 
RECEIVE CDIN INTO MSG; 
IF CDIN.STATUS NOT = 99 THEN 
INITIALIZE BATCH MODE; 
DO BATCH PROCESSING; 
INITIALIZE_ONLINE MODE; 
EXIT_COMS; 
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Initializing COMS 


This step of the batch recovery program should open the database to be updated, 
establish a link to COMS, and initialize the restart class. It should also find the restart 
class entity for this program. For more information on initialization, see Section 3, 
“Communicating with COMS through Direct Windows.” For more information on the 


restart data set, see Section 6, “Interactive Recovery.” 


Following is the program flow for the initialization step of the batch recovery program: 


KKEKEKRKERKREEKEEEKREEK 


* INITIALIZE COMS * 


KREKEKKKEKEKKEREKEE 


OPEN FILE | 
OPEN UPDATE DATABASE 

ON EXCEPTION 

STOP RUN; 

ESTABLISH COMS LINK; 
ENABLE INPUT COMS "BATCH"; 
RECEIVE CDIN INTO MSG 

NO DATA RESET FOUND_RECOVERY MESSAGE 
ELSE | 
SET MY_BATCH_RESTARTED; 
SET FOUND RECOVERY MESSAGE; 


IF NOT FOUND RECOVERY MESSAGE 
SELECT RSTQD FROM RSTINFO 
WHERE RST-PROG-DESG = MY-PROG-DESG; 
RETRIEVE RSTQD 
ON EXCEPTION 
MOVE 1 TO WS-RETRIEVE-FIELD; 
IF RSTINFO-NOT-RETRIEVED 
INSERT RSTINFO | 
ASSIGN WS-PROG-NAME TO RST-PROG-NAME 
ASSIGN MY-PROG-DESG TO RST-PROG-DESG 
ASSIGN MY-RESTARTINFO TO RST-INFO; 
REPOSITION FILE 
IF RSTINFO-RETRIEVED 
SET MY_BATCH_RESTART3 
IF FOUND_RECOVERY_MESSAGE THEN 
DO_INITIAL_BATCH_RECOVERY; 


Initializing Interactive Mode 


Interactive mode allows a program to receive nonrecovery transactions, and to be 
signaled when to go to end of job (EOJ). It deletes an eventual batch mode restart class 


entity. 
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Following is the program flow for initializing the interactive mode in the batch recovery 
program: 


KKEKKKKKKEKKEKREKKEKEKREERREEEK 


* INITIALIZE ONLINE MODE * 


KKEEKEKKEKKKEKKEKKEKKEKEEKREKKEEKE 


BEGIN-TRANSACTION; 
DELETE RSTINFO 
WHERE RST-PROG-DESG = MY-PROG-DESG; 
ENABLE INPUT CDIN "ONLINE"; 
MOVE CDIN.PROGRAMDESG TO MY-PROG-DESG; 
END-TRANSACTION; 


Initializing Batch Mode 


Initializing batch mode allows your program to receive only recovery transactions. This 
program subroutine also informs COMS of the switch from interactive to batch mode. 
Following is the program flow for initializing batch mode within your batch recovery 
program: 


KEKKKEKRKKKEREKREKRRERREREEER 


* INITIALIZE BATCH MODE * 


KRKEKEKRKKEKRERREREEKEKEEEEE 


ENABLE INPUT CDIN "BATCH"; 
MOVE CDIN.PROGRAMDESG TO MY-PROG-DESG; 


Initial Batch Recovery 


You can use the batch recovery subroutine to allow your program to participate in 
the COMS recovery and archival recovery when it receives a recovery transaction in 
INITIALIZE _COMS. This subroutine receives recovery transactions and updates a 
database. 


Following is the program flow for doing initial batch recovery within the batch recovery 
program: 


KREKKKEKRERERKKERRERERRREEREEE 


* DO_INITIAL_BATCH_RECOVERY * 


KKREKEKKKEKKREKRKEKRRKEKREREERRER 


RESET NO_MORE_RECOVERY 
WHILE NOT NO MORE RECOVERY DO 
HANDLE_RECOVERY_TRANSACTION; 
RECEIVE CDIN INTO MSG 
NO DATA 
SET NO_MORE_RECOVERY; 
REPOSITION FILE; 
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Error Recovery 


Use this subroutine when an error is returned from either BEGIN-TRANSACTION or 
END-TRANSACTION statements. The error indicates that the transaction has not 
been committed to the database. COMS submits this transaction to the program by 
way of the RECEIVE statement. The subroutine receives the recovery transaction and 
updates the database. 


Following is the program flow for handling begin- and end-transaction errors within the 
batch recovery program: 


KKK KIKI AKI KAKA KIKI 


* DO _BTR_ETR_ERROR RECOVERY * 


KKEREKEKRKKKRERKEKKKRERRKEKRREREKRE 


RESET NO_MORE_RECOVERY 
RECEIVE CDIN INTO MSG 
NO DATA 
SET NO_MORE_RECOVERY 
ELSE 
HANDLE_RECOVERY_TRANSACTION 


Handling the Recovery Transaction 


Following is the subroutine for handling the recovery transaction within the batch 
recovery program: 


HEKKKKKKEKKRREREKEKRKERERKKEKEKREEKAKEEE 


* HANDLE RECOVERY _TRANSACTION * 


KEEKEKEKKEKEKREREKKKRRKEREKRRREEEREE 


SIMULATE_ORIGINAL_TRANSACTION; 
MOVE MY_RESTARTINFO TO CDIN.CONVERSATION.RESTARTINFO; 
BEGIN-TRANSACTION CDIN USING MSG; 
UPDATE_DATABASE; 
MODIFY RSTINFO 
ASSIGN MY-RESTARTINFO TO RST-INFO 
WHERE RST-PROG-DESG = MY-PROG-DESG; 


END-TRANSACTION CDOUT 


Batch Processing 
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Use the batch processing subroutine to update a database until the processing is done. 
This subroutine stores restart information necessary to identify where to continue for 
recovery. This is done both in the transaction trail (using the Conversation Area field of 
the input header) and in the restart class. 
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Following is the program flow for batch processing within the batch recovery program: 


KKEREKEKKKERKEKKEKREREKRRRKREEE 


* DO BATCH PROCESSING * 


KREKKKKKEKKEKERKEKKKEEEEKR 


DO 


MOVE MY_RESTARTINFO TO CDIN.CONVERSATION.RESTARTINFO; 
BEGIN-TRANSACTION CDIN USING MSG; 
UPDATE_DATABASE; 
MODIFY RSTINFO 
ASSIGN MY-RESTARTINFO TO RST-INFO 
WHERE RST-PROG-DESG = WS-PROG-DESG; 
END-TRANSACTION CDOUT; 
UNTIL ALL_WORK_DONE; 


Transaction State 


Batch application programs must use a BEGIN-TRANSACTION statement that 
identifies the message variable for entering transaction state. Moreover, the message 


variable must contain an image of the batch transaction read from the disk file or tape 
file. 


These requirements are necessary to allow COMS to capture an image of the transaction 
on the transaction trail. Then, if the database is ever rolled back, COMS can resubmit 
the transaction to the batch application in coordination with the resubmission of the 
online transactions. Another benefit is that the batch file that contained all the original 
input transactions does not need to be present during archival recovery. 


Following is the program flow for transaction state processing within the batch recovery 
program: 


KREKKEKEKEEKREERKEKRERERKEEEKE 


* BEGIN TRANSACTION TIME * 


KRKEKKERKRERRRKRKERERKERRERE 


_ BEGIN-TRANSACTION CDIN USING MSG 
ON EXCEPTION 
DO_BTR_ETR_ERROR_RECOVERY; 


KKKKKKEREKKEREKRRERRRREEER 


* END TRANSACTION TIME * 


KEKKERKREEKRRKKEREREREREERE 


END-TRANSACTION CDOUT AUDIT RDS 
ON EXCEPTION 
DO_BTR_ETR_ERROR_RECOVERY; 
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Section 8 
Security 


COMS automatically performs security checks, provided that a message-routing 
and security scheme has been defined with the COMS Utility program and stored 
in the configuration file. For more information on COMS security, see the COMS 
Configuration Guide. 


This section provides information on the security-checking routines that you can write 
into application programs and processing items to augment COMS security or to function 
independently. This type of security checking is called programmatic security. You can 
also use security category designators and usercode designators in application programs 
and processing items to assist in performing security checks on a more refined level than 
COMS can do alone. 


To use security categories and other security-related COMS entities for programmatic 
security, you must have declared an input header and an output header in your program. 
You also need to use COMS service functions when writing routines for programmatic 
security. Refer to Section 3, “Communicating with COMS through Direct Windows,” 

for additional information about the input and output headers. Refer to Section 4, 
“Accessing Service Functions,” for information about the service functions. 


When to Use Programmatic Security 


Although COMS provides highly effective and flexible tools for configuring a COMS 
security scheme, some degree of programmatic security is an alternative to consider 
under the following circumstances: 


e You want to perform more refined security checking than COMS security alone can 
provide. 
e You are not using trancodes for message routing or security checking. 


e You are using trancodes for message routing, but you have not assigned security 
categories to the trancodes you are using. 


e You are using trancodes to which security categories have been assigned, but you 
want to perform an additional security check after the program retrieves arecord — 
from the database. 


e You want to provide data-dependent security. 


Using the Input Header in Security Checking 


The input header is a message header that provides routing and other descriptive 
information about received messages. When you use an input header in a program that 
runs under COMS, COMS places values into the fields of the input header each time the 
program receives a message. 
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The following list, which provides the types of information that COMS places in the input 
header fields, can be used in security checking: 


e The usercode associated with the message 
e The security categories associated with the session that originated the message 


e The module function index (MFI) representing the trancode associated with the 
message 


e The time and date when the message was first encountered by COMS 
e The station or program that originated the message 


The following paragraphs describe specific techniques you can use for security checking 
_In programs that contain an input header. Since most values that COMS places into 

the input header fields are designators, you have to call service functions of the COMS 

library to exchange the designators for names. Refer to Section 4, “Accessing Service 

Functions,” for more information about the service functions. Refer to Section 3, 

“Communicating with COMS through Direct Windows,” for more information about the 

input header. 


Using the Usercode Designator 


When a program receives a message, the Usercode field of the input header contains a 
designator representing the usercode associated with the incoming message. You can 
call the GET_ NAME USING_DESIGNATOR service function to exchange the usercode 
designator for a usercode name. 


A program can perform a security test by checking the usercode associated with a 
particular message against a list of usercodes kept in the program. This type of security . 
test is not the most efficient kind of programmatic security you can use, but it could be 
useful if you are not using trancodes or security categories. 


Using the Security Designator 


When a program receives a message, the Security Designator field of the input header 
contains the security designator for the session, which represents the intersection of 
the security-category lists assigned to the usercode and the station that originated the 


incoming message. 


If a security-category list is assigned to your program, COMS provides a way to 

find out whether any security category in the list of the program intersects with 

the security-category list of your session. You simply have the program call the 
TEST_DESIGNATORS service function to test the validity of the security category. 


Using the Module Function Index 
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If a process-security error occurs, the Function Status field of the input header contains 
a value to indicate the error condition. For the meaning of this and other values and 
mnemonics, see Appendix A. 
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If you have associated positive MFIs with your trancodes or group of trancodes and have 
not associated security categories with those trancodes, you can use the MFIs to point 
to the appropriate code that determines whether the user who entered the message 

is allowed to submit this kind of trancode. Refer to “Using Module Function Indexes 
with Input” in Section 3, “Communicating with COMS through Direct Windows,” for 
information about MFIs. Using the usercode designator and/or the session-security 
designator are other possible methods for checking user validity. 


Checking Database Records After Retrieval 


This technique can be combined with other programmatic security techniques to produce 
a more refined security check than is possible with COMS security alone. The technique 
involves the program actually retrieving a database record before making the final 
decision as to whether a certain security-category list entitles the user to see or update 
the particular database record. Following are two examples of how to use this technique. 


Example 1 


At the ABC Company, a particular trancode has been defined to identify a transaction 

as an inquiry into the personnel database. Employees who work in the Shipping and 
Receiving Department obviously should not be permitted to make inquiries about 
personnel records. So the trancode representing the personnel inquiry transaction is not 
assigned to the window that Shipping and Receiving employees use to communicate with 
COMS. 


However, a clerk who works in the Personnel Department is permitted to inquire about 
personnel records, except for his own personnel record and the personnel records of 
upper management. The inquiry transaction always works the same way, except that 
each personnel record belongs to a different person. Because the program does not 
know until the inquiry has been made who the record belongs to, the program must 
perform a security test of record names to determine whether the record is one of the 
few records that the personnel clerk is not allowed to see. 
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Example 2 


Following is an example of making a more refined decision by using programmatic 
security checking. 


At the XYZ Company, suppose that security categories have been defined for the 
following employee levels: 


e Senior manager 
e Junior manager 
e Clerk 


Suppose that the Payroll Department has a rule that permits senior managers to access 
only their own payroll records and those belonging to junior managers, while permitting 
junior managers to access their own payroll records and the payroll records of everyone 
else except for senior managers. Payroll clerks are permitted to see only their own 
payroll records and those belonging to other payroll clerks. 


The security requirements of this situation are too complicated for COMS to handle 
alone. Whenever a payroll transaction is entered, authority of the user to see a payroll 
record of a senior manager, junior manager, or clerk depends on the identity of a 
particular record in the data base. Therefore, the program needs to do a more refined . 
security check. 


First, the program could find the record on the database and determine what kind of 
employee it belongs to. Next, the program could find out, through a programmatic 
convention, whether the security category associated with the record is in the 
security-category list for the session that originated the transaction. To do this, the 
program would call the TEST _DESIGNATORS service function. At this point, the 
program is ready to decide whether the transaction is valid for this record. 


If the company hires a new manager, he or she just needs to be given his or her own 
usercode with the appropriate security categories assigned to it. The security-checking 
routines in the program need not be adjusted, nor the program recompiled. 


When the destination is a station, the message is a program-to-station message. COMS 
security permits a program to send a processed message back to the originating station. 
Alternatively, a program can send a message to any station or window dialogue within 
the window of the program. In addition, a program can send a message to a printer, 
which is known to COMS as a single-output window and defined with the Network 
Definition Language II (NDLI]) as MYUSE = OUTPUT. 


When ihe destination for a processed message is another transaction-processing 
program, the message is a program-to-program message. COMS security permits 
a program to send a message to another program only when the security category 
belonging to the trancode in the message is in the security-category list assigned to 
the destination program. Refer to “Routing Messages by Specifying a Destination” 
in Section 3, “Communicating with COMS through Direct windows” for additional 
information. 
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Thus, the primary purpose of COMS process security is to prevent programs from 
processing transactions submitted by users or programs who are unable to obtain the 
security clearance required by COMS. 


How COMS Handles Security Errors 


When a user fails access security and cannot log on to a particular station or window, the 
Menu-Assisted Resource Control (MARC) program sends an error message to the user. 
Refer to the MARC Operations Guide for a list of error messages that can be received in 
regard to access security. 


When a message fails process security, the failure occurs because the security-category 
list of the user or program submitting the message does not include the security category 
associated with the trancode in the message. Under these circumstances, COMS assigns 
the failed message to the default agenda for the window. 


Like all agendas, the default agenda must specify a program as a destination for 
messages, and can specify a list of processing items. The existence of a default agenda 
must be defined with the COMS Utility program and stored in the configuration file.. You 
must write a destination program containing an input header and an output header if 
you want COMS to identify a security error and PED OES it in the Function Status field of 
the input header of your program. 


The program you write to handle security errors does not have to be written solely for 


error-handling. It can be an ordinary application program that is capable of processing 
various transactions associated with valid MFIs as well as handling security errors. 
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Section 9 
Communicating with COMS through 
Remote-File Windows 


As an alternative to using direct windows to access a station or program in COMS, you 
might want to use remote-file windows for the following reasons: 


e You have existing programs that use the remote-file interface, either from the 
Generalized Message Control System (GEMCOS), the Command and Edit (CANDE) 
MCS, another Unisys software product, or user-written applications. 


e You want to create a time-sharing type of application. You want to ensure that if 
multiple copies of a program are running, only one copy of that program will receive 
input from any particular user. 


With remote files, each program is associated with a set of users. Messages entered in a 
current window are sent to the program associated with that window. This differs from 
use of direct windows, in which multiple copies of a program read from a common queue. 
In remote files, every message from a station is processed by the same copy of a program. 
In direct windows, the current message from a station might be processed by one copy of 
a program, while another message from that same station might be processed by another 
copy of the program. 


For further information on remote files and file attributes, see the A Series I/O 
Subsystem Programming Guide. For further information on task attributes, see 

the A Series Work Flow Administration and Programming Guide. For additional 
information about remote files in COMS, connected with a comparison between COMS 
and CANDE, see the COMS Migration Guide. 


There are two kinds of remote-file windows: dynamic and declared. The following two 
parts of this section tell you how to use each kind of remote-file window. 


Dynamic Remote-File Windows 


You can use dynamic remote-file windows to open to program environments that are not 
defined to COMS. 


For example, when you are in a Menu-Assisted Resource Control (MARC) window 
session, you might want to run a remote-file program. MARC initiates the program and 
sets the STATION task attribute to the name of the station you are currently using. 
Since this task attribute is set, COMS is called to handle the opening of the remote file. 
When your program executes a statement to open a remote file, COMS approves the 
opening of the file and associates a dynamic window with it. MARC requests COMS 

to change the current window from a MARC window to the just-opened dynamic 
remote-file window, which might be identified as REM0001. 
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When you close the remote-file window, your current window is changed to the MARC 
window dialogue you were in before you opened the remote-file window. It is important 
to be aware of what your current program environment is, particularly if you move 
among several windows without closing them. 


Dynamic remote-file windows can also be created when a remote-file program initiates a 
connection to a station on its own. The remote-file program initiates this connection in 
its remote file by adding the station to the remote-file station list. When the remote-file 
program requests a station that is connected to COMS, COMS opens a dynamic window 
for the station. You are not notified directly that the window has been opened, but 
you can use the COMS ?WINDOWS command to verify that it has. Then, you can use 
the COMS ?ON command (as in ?ON REM0O02) to change the current window to the 
remote-file window. | 


One dynamic remote-file window is established per user. If the user at station one 
submits a ?WINDOWS command, he or she might receive the message that the dynamic 
window that has been opened is REM0001. If another user submits the window 
command, he or she receives a message that a different dynamic window, such as 
REM0005, has been opened, and yet these users might both be accessing the same 
remote-file program through the same remote file. 


Declared Remote-File Windows 


You can use declared remote-file windows to create either single-user or multiuser 
environments within COMS. To declare a remote-file window, you need to run the 
COMS Utility. In the COMS Utility, you name your remote-file program and can set 
various options, such as number of users per program copy or number of copies of the 
program allowed. For more information on using the COMS Utility, see the COMS 
Configuration Guide. 


The relative station numbers (RSNs) associated with remote files become particularly 
important with declared remote-file windows. An RSN is associated with each station 
in a remote file, depending on the number of program copies and users per copy you 
have set in the COMS Utility. When you close a window, COMS causes the remote-file 
program to receive an end-of-file (EOF) indication. Your program should check the 
LASTSTATION file attribute to determine on which RSN the EOF was given. If 
LASTSTATION is RSN 1, you should go to end of job (EOJ). If you receive any other 
RSN number, this means that the station associated with that RSN has closed its 
connection to the remote-file program; you might want to clean up local storage. 


Single- User Declared Windows 
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Within COMS, when you move to a window using the COMS ?ON command for 
single-user remote-file declared windows, COMS starts the remote-file program and sets 
the task attribute USERCODE. On the Program Activity menu of the COMS Utility, 
you can specify a usercode under which you would like your programs to run. If you 

do not do this, COMS assigns the usercode with which you logged on to COMS to the 
remote-file program it starts when you submit the ?ON RMT command. 
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| Communicating with COMS through Remote-File Windows 


In a single-user declared remote-file window, each copy of a program is dedicated to 

one station. If another station tries to access the remote-file window, COMS starts a 
separate copy of it for that user. When no usercode is set in the Program Activity menu _ 
of the COMS Utility, COMS assigns to that copy the usercode currently logged on at the 
station. 


Each remote-file window in a single-user environment has only one RSN assigned to 

it. If you decide to close this type of window, COMS causes an EOF indication to send 
the program to EOJ. Also, if COMS wants your program to go away for any reason, the 
program receives an EOF. 


Multiuser Declared Windows 


If you want to have multiuser declared windows, set the number of users to more than 
one in the Program Activity menu of the COMS Utility. Within COMS, when you submit 
the command ?ON RMT, COMS starts the remote-file program and sets the STATION 
task attribute to a special COMS station. 


If in the COMS Utility you have set the number of users to two, COMS is able to assign 
two users to each copy of the remote-file program. The following example shows how 
COMS would route three users who want to access the same remote-file program. 


Remote files have RSNs associated with them. RSN 1 for a remote file is reserved by 
COMS for its own record-keeping purposes. The second and third RSNs for the remote 
file designate the stations that can be attached to this remote file, since the number of 
users has been set to two. Ifa third user tries to access the remote-file program, COMS 
initiates another copy of the program and uses RSN 1 for its own record keeping. Then, 
RSN 2 designates the station of the third user. 


If the first user decides to close his or her window, COMS causes the remote-file program 
to receive an EOF indication. This indicates that the program of the user needs to check 
the LASTSTATION file attribute to determine on which RSN the EOF was given. In 
this case, the second user is still attached to the remote file through RSN 3. Therefore, | 
the program might clean up the local storage for RSN 2, but the program should not 
terminate because there is still a user attached to it. When the second user closes, 

the program receives an EOF indication for RSN 3, and the program might clean up 

the storage for RSN 3. Because this is the last station associated with this copy of the 
program, COMS sends an EOF indication on RSN 1 to indicate that the program should 
go to EOJ. This EOF indication is sent even though there is a user attached to another 
copy of the remote-file program (the third user, represented by RSN 2 in the second copy 
of the remote-file program). 


Additional Programming Notes for Remote-File 
Windows 


When communicating with COMS through remote-file windows, be sure to observe the 
precautions and limitations described in this section. 
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Communicating with COMS through Remote-File Windows 


Designation of Input or Output Files 


When you use remote-file windows, the usual kind of file you will be opening is an 
input/output file. However, you might want your program to open files that are input 
only or output only. In COMS, as in CANDE, you can open several output files. 

In declared remote-file programs, all output files are associated with the declared 
remote-file window established in the COMS Utility. You should declare only one 
input-capable file, and that should be associated with the established declared remote-file 
window. 


In dynamic remote-file programs, all output files are associated with the same dynamic 
window and the first input-capable remote file is also associated with this window. All 
subsequent input-capable files are assigned different dynamic windows. 


Tanking and Multiuser Remote-File Windows 


If you are writing a program for a multiuser remote-file window, you should set the 
TANKING file attribute to SYNC or ASYNCH. When you use either of these values, 
the output for the remote file is tanked, and the remote file program continues after 
the remote file closes. The default value for TANKING is NONE. Be aware that if this 
attribute is set to NONE, a user whose terminal is on local or on another window can 
prevent all other users of this window from receiving output. If the attribute is set to 
NONE and the TIMELIMIT file attribute is used, COMS gives a timelimit exception 
when the number of outstanding characters for a station exceeds 2400 characters. This 
range of characters includes data comm headers. 


Remote-file programs written to run under COMS must not write to the file until the 
processing of the OPEN statement is completed. To make sure that this happens, 
always wait until an input is received for a read operation. If necessary, use notification 
text to provide this input on a declared remote-file window. 


Exception Handling 


When you are writing remote-file programs for use in the COMS environment, use 
exception handling for read and write operations. Your program should always check 
both read and write operations for the presence of EOF exceptions. When an EOF 
exception is found, the program should check its LASTSTATION file attribute to find 
out what to do. . 


COMS gives a time limit exception if TANKING is set to NONE and a TIMELIMIT 
attribute is used when the number of outstanding characters for a station exceeds the 
maximum limit for the specified time limit. If a broadcast operation is done, COMS gives 
a time limit exception if output could not be sent to any of the stations in the remote file. 


If the attribute is set to NONE and the file attribute TIMELIMIT is used, COMS 
suspends output to the file when the number of outstanding characters for a station 
exceeds the limit of 2,400 characters, including data comm headers. When the time 
limit expires, COMS gives a time limit exception to the program attempting the write — 
operation. . 
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Appendix A 
Tables of Values and Mnemonics 


The following tables contain the values and mnemonics your program looks for 

in response to the execution of various program statements. The tables give 
quick-reference information for the Function Status and Status Value fields of the input 
header, the Status Value field of the output header, result messages for service function 
calls, and service function security category values and mnemonics. 


8600 0650-000 A-1 


Tables of Values and Mnemonics 


Input Header Function Status Field Values and 
- Mnemonics 


Different syntax is used to access mnemonics in different languages. RPG uses the 
mnemonic as a figurative constant, which is the name preceded by an asterisk (*). In 
Pascal, mnemonics are context-sensitive identifiers. 


Function Status fields passed to MARC also contain additional information in bits 
[38:19]. Therefore, any processing items to be placed in the MARCINPUT agenda 
should handle messages with nonzero values in this field. The values within this field are 
to be used solely for communication between COMS and MARC, and they might change 
on any release without notification. 


Table A~1 shows the values and mnemonics of the input header Function Status field. 


Table A-1. Input Header Function Status Field Values and Mnemonics 


COBOL/ALGOL Pascal 
Value RPG Mnemonic Mnemonic Description 


NULFNCTN NULLFNINDX The field value is zero. 


CTLMSG CTLMSG MARC message. 
NOWNDW NOWNDW No window is available. 


LOST LOST No destination is available to 
receive messages. 


BADTCODE BADTCODE The message has been routed to 
the default agenda because one of 
the following two conditions has 
occurred: 


e COMS has detected an 
alphanumeric trancode that 
has not been defined to 
COMS. 


COMS has detected a 
trancode beginning with an 
alphanumeric character 
followed by a special 
character or characters. 


NOTCODE NOTCODE A trancode beginning with a 
nonalphanumeric character has 
been found. The message will be 
routed according to the default 
agenda. 


continued 
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Tables of Values and Mnemonics 


Table A-1. Input Header Function Status Field Values and Mnemonics (cont.) 


COBOL/ALGOL 
Value RPG Mnemonic 


CTLNOWDW 


CTLTOMCS 


ONMARC 


SECTYERR 


NOITEM 


TRDIVRT 


GOODDEL 


BADDELVY 


BADDATA 
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Pascal 
Mnemonic 


CTLNOWDW 


CTLTOMCS 


ONMARC 


SECERR 


NOITEM 


TRDIVRT 


GOODDELVY 


BADDELVY 


BADDATA 


Description 


A controlled message is pending 
without an available window. 


A controlled message has been 
sent to the MCS. 


The MARC window is now 
available. 


A process-security error has 
occurred because the trancode 
associated with the incoming 
message is not allowed for this 
station or session. 


An attempt was made to apply a 
processing-item list to a message, 
but an item of the list was not 
found. As. a result, the message is 
sent to the default agenda. 


A message has been diverted from 
a dialogue that is in transaction 
mode. 


Delivery of the message is 
confirmed. 


A break condition has caused 
output from a direct window to be 
discarded. 


For a CP 2000 station, rejection of 
a message for which delivery 
confirmation was requested. 


For a CP 2000 station, rejection of 
a message for which delivery 
confirmation was not requested. 


- continued 
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Input Header Function Status Field Values and Mnemonics (cont.) 


COBOL/ALGOL 
RPG Mnemonic 


OPNOTEXT 


ONNOTEXT 


_ BADTPDEL 


CTLRMSG 


OUTMSG 


RTNMSG 


RMTFILE 


CLOSMARC 


STSECMSG 


NOSECMSG 


PREVATT 


TERMATT 


Pascal 
Mnemonic 


OPENNOTEXT 


ONNOTEXT 


BADTPDELVY 


CTLRMSG 
OUTMSG 
RTNMSG 
RMTFILE 
CLOSMARC 
STARTSECMSG 
STOPSECMSG 


ALREADYATT 


ATTACHED 


Description 


When you define a direct window 
in the COMS Utility and do not 
add open-notification text, COMS 
returns this value upon each 
request for an open. 


When you define a direct window 
in the COMS Utility and do not 
add on-notification text, COMS 
returns this value upon each 
request for an on. 


Delivery confirmation has been 
requested for a TP-to-TP message. 
This value notifies the sending 
program that the message has not 
been delivered. 


Control message. 
Output message. 
Return message. 
Remote file activity. 
Close MARC window. 
Start security message. 
Stop security message. 


Successful! attachment; station 
was already attached. 


Successful attachment; station 
was attached through an enable 
statement. 


continued 
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Table A-1. 


COBOL/ALGOL 
Value RPG Mnemonic 


WAITBUSY 


WAITATT 


DIALOK 


ATTPEND 


NOHOST 


PROTERR 


NORSRCS 


NOTDEF 


BADCALL 


NOTAVAIL 
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Pascal 
Mnemonic 


WAITNOTBUSY 


WAITATT 


DIALOUTOK 


PENDINGATT 


NOHOST 


PROTOCOLERR 


NORESOURCES 


NOTDEFINED 


CALLFAILED 


NOTAVAIL 


Input Header Function Status Field Values and Mnemonics (cont.) 


Description 


Attachment pending; waiting for 
station to become not busy. 


Attachment pending; waiting for 
physical attachment. 


The requested dial-out over a 
modem was completed. 


An attachment request was 
offered; waiting for a match from 
the other host. 


COMS made attachment offer; 
other host not available. COMS 
cancels pending attach. 


Failure during request to attach; 
protocol error. 


Failure during request to attach; 
resources available. 


Failure during request to attach; 
station not defined. 


Failure during request to attach; 
station in use. 


Failure during request to attach; 
station not physically attached. 


Failure during request to attach; 
the BNA ESTABLISH CALL 
command failed. 


Failure during request to attach; 
station not available. 


Tables of Values and Mnemonics 


continued 
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Table A-1. Input Header Function Status Field Values and Mnemonics (cont.) 


COBOL/ALGOL 
Value RPG Mnemonic 


BADDIALI 


DIALINC 


RETAINED 


NORTAIND 


DIALDISC 


SHUTDOWN 


DISABLED 


TOOMANY 
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Pascal 
Mnemonic 


BADDIALINIT 


DIALINCOMPLETE 


NOREQUEST 


RETAINED 


NOTRETAINED 


DIALDISCONNECT 


SHUTDOWN 


DISABLED 


TOOMANY 


Description 


COMS was unable to initiate the 
requested dial-out. 


COMS was unable to complete the 
requested dial-out. — 


Successful detachment; the 
window was closed. 


Successful logical detachment; the 
CP 2000 terminal gateway 
retained the physical attachment. 


Successful logical and physical 
detachment from a CP 2000 
Station. 


Successful detachment from an 
NSP station that had been 
attached through a modem. 


Program is asked to terminate 
because COMS is shutting down. 


Program is asked to terminate 
because a DISABLE entity 
command was entered. The entity 
is the COMS entity (for example, 
DISABLE < entity type> 

< entity name > ) that caused 
program termination. This entity 
could also be a program, a 
window, or a database. 


Program is asked to terminate 
because activity was reduced and 
current copies exceeded minimum 
copies. 


continued 
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Tables of Values and Mnemonics 


‘Table A-1. Input Header Function Status Field Values and Mnemonics (cont.) 


COBOL/ALGOL Pascal 
Value RPG Mnemonic Mnemonic Description 


-100 (not applicable) (not applicable) An invalid input message key was 
detected by the SDF formlibrary. 
An input error has occurred, and 


the application program should 

perform error handling. Typically, 
this error indicator is received on 
the first input when SDF is used. 
SDF takes no action on the input 


message. 
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Input Header Status Value Field Values and 
_Mnemonics 


Different syntax is used to access mnemonics in different languages. RPG uses the 
mnemonic as a figurative constant, which is the name preceded by an asterisk (*). In 
‘Pascal, the mnemonics are context-sensitive identifiers. 


Table A-2 shows the input header Status field values and mnemonics. 


Table A~2. Input Header Status Field Values and Mnemonics 


COBOL/ALGOL. Pascal/RPG 
Value Mnemonic Description 


COMSOK Successful incoming message. 


NORQST The station designated for a dynamic 
attachment or detachment is invalid or 
unknown, the specified hostname does 
not match, or the host system has denied 
access to the station. 


SKIPNEXT A batch synchronized recovery transaction 
has aborted outside of the transaction 
state. The program should skip the 
returned successful message, skip the next 
failed message, and then continue. 


BADMSGSZ The input message has been truncated 
because it was larger than the input 
message area provided in the RECEIVE 
statement. 


A batch synchronized recovery transaction 
has aborted after mid-transaction. The 
transaction caused the program to abort 
and must not be reprocessed. 


NODATA There is no message to be received by 
your program. 


OKRECOV Successful incoming message is being 
resubmitted for synchronized recovery. 


continued 
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Table A-2. Input Header Status Field Values and Mnemonics (cont.) 


COBOL/ALGOL Pascal/RPG 
Value Mnemonic Description 


BADPREV Successful incoming message was 
submitted once and caused the program 
to abort, so is being resubmitted again. If 
the message causes another abort, the 
originating station will be notified and the 
message discarded. 


BADDEST A processing item has attempted to 
reroute an input message and one of the 
following conditions has occurred. 


e Aninvalid program designator was 
detected while a processing item 
attempted to route a message from 
one application program to another. 


An invalid station designator was 
detected while a processing item 
attempted to send a message. 


- BADAGND An invalid agenda designator was detected 


while a processing item was attempting to 
reroute an input message. 


NODEST The destination program of an application 
program message was not enabled while a 
processing item was attempting to reroute 
an input message. 


COMS has directed the application © 
program to terminate. The Function 
Status field of the input header will show 
one of three values (-60, -61, -62) or 
corresponding mnemonics, depending on 
the reason for the termination. 


DIALING The destination station for an attempted 
dynamic attachment is already attached 
to another program. 


BADDIAL An attempted dial-out over a modem 
failed. 


continued 
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Table A-2. Input Header Status Field Values and Mnemonics (cont.) 


COBOL/ALGOL Pascal/RPG 
Value Mnemonic Description 


BADDCNCT An attempted dynamic attachment from a 
dial-out station failed. 


BADENBLE An attempt to add a window to a window 
list of a station list failed. 
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Output Header Status Value Field Values and 
Mnemonics 


Different syntax is used to access mnemonics in different languages. RPG uses the 
mnemonic as a figurative constant, which is the name preceded by an asterisk (*). In 
Pascal, the mnemonics are context-sensitive identifiers. 


Table A-3 shows the output header Status Value field values and mnemonics. 


Table A-3. Output Header Status Value Field Values and Mnemonics 


~ COBOL/ALGOL Pascal/RPG 
Value Mnemonic Description 


COMSOK . The outgoing message has been accepted 
for transmission. 


POINVDST The specified TP destination for the 
protected output message is invalid; this 
TP is associated with a window that is 
either not protected or is protected by a 
different protected output file. Used only 
by applications generated by LINC 
Release 14. . 


A successful transaction commit has been 
reached; therefore, no further protected 
output is allowed for this transaction. 
Used only by applications generated by 
LINC Release 14. 


POTOTP A protected TP-to-TP message has already 
been generated; only one such message is 
allowed for each protected transaction. 
Used only by applications generated by 
LINC Release 14. 


BADMSGSZ The length of the output message 
specified in the Text Length field of the 
output header was larger than the output 
message area. 


OKRECOV The outgoing message has been accepted, 
but will be discarded because COMS is 
processing a recovery transaction. 


BADDEST One of the following two conditions has 
occurred: 


continued 
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Table A-3. Output Header Status Value Field Values and Mnemonics (cont.) 


COBOL/ALGOL Pascal/RPG 
Value Mnemonic Description 


The outgoing message was rejected 
because the station designator for the 
destination was invalid. 


An invalid program designator was 
detected while a processing: item 
attempted to route a message from 
one application program to another. 


BADAGND The outgoing message was rejected 
because the agenda designator in the 
Agenda Designator field of the output 
header was invalid. 


AGNDQUIT The outgoing message was prematurely 
stopped by a processing item. This error 
number is intended to be used as an error 


signal from the processing item to the 
calling program. 


NODEST One of the following conditions has 
occurred: 


The outgoing message was rejected 
because the station is not open to 
this window. 


The destination program of an 
application program message is not 
enabled. 


The destination program and its 
associated database are disabled. 


The outgoing message was rejected 
because it contained an invalid 
trancode and no default output 
agenda was specified. 


continued 
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Table A-3. Output Header Status Value Field Values and Mnemonics (cont.) 


COBOL/ALGOL Pascal/RPG 
Value Mnemonic Description 


STOPPROC One of the following conditions has 
occurred: 


e Asecurity error was detected when a 
program routed a request from one 
application program to another 
program specified by the transaction 
code in the message. 


A processing item in the 
processing-item list associated with 
the requested agenda was not 
available. COMS stopped processing 
the processing-item list when the 
unavailable processing item was 
encountered. 


MSGTOOBG The outgoing message was rejected 
because it was too large to be processed. 


DBDSBLED The database associated with the 
destination program is disabled. 


The window and database of the 
destination program are disabled. 


The connection establishment process is 
still in progress because of a prior 
ENABLE TERMINAL request. The 
outgoing message has been rejected. 
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Service Function Result Values and Mnemonics 


Table A-4. shows the service function result value integers for ALGOL, COBOL, and 
RPG, the service function result value mnemonics for Pascal, and a description of what 
occurs when these integers or mnemonics are executed. 


Table A-4. Service Function Result Values and Mnemonics 


COBOL/ALGOL Pascal/RPG 
Value Mnemonic 


OK 


FUNCFAIL 


INVDESG 


SHORTARRAY 


NOINSTDATA 


A-14 


Description 


Function completed successfully. 


Error. Function failed because of invalid 
name or designator. 


Designator error. Invalid designator. 


Array size error. Supplied array was too 
short to house the information. 


No-data error. The requested installation 
data was not present in the configuration 
file. 
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Service Function Security Category Values and 


Mnemonics 


Different syntax is used to access service function security category values and 


Tables of Values and Mnemonics 


mnemonics in different languages. RPG encloses the mnemonic in single quotation 
marks (alpha literal). In Pascal, the mnemonics are context-sensitive identifiers. 


Table A-5 shows the service function security category values or mnemonics for ALGOL, 
Pascal and RPG, and COBOL74 in columns 1, 2, and 3, respectively. 


Table A-5. Service Function Security Category Values and Mnemonics 


ALGOL 
Value 
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Pascal/RPG Mnemonic 


STATION 
USERCODE 
AGENDA 
PROGRAM 
SECURITY 
SECTYCAT 
DEVICE 
STNLIST 
DVCLIST 
WINDOW 
DATABASE 
PROCITEM 
PRITMLST 
TRANCODE 
WNDWLST 
LIBRARY 
CATLIST 
INSTDATA 
INSTINT1 
INSTINT2 
INSTINT3 
INSTINT4 
INSTINTS 
INSTSTR1 


COBOL74 Name 

STATION 

USERCODE 

AGENDA 

PROGRAM 

SECURITY 
SECURITY-CATEGORY 
DEVICE 

STATION-LIST 
DEVICE-LIST 

WINDOW 

DATABASE 
PROCESSING-ITEM 
PROCESSING-ITEM-LIST 
TRANCODE 

WINDOW-LIST 

LIBRARY 

CATEGORY-LIST 
INSTALLATION-DATA 
INSTALLATION-INTEGER-1 
INSTALLATION-INTEGER-2 
INSTALLATION-INTEGER-3 
INSTALLATION-INTEGER-4 
INSTALLATION-INTEGER-ALL 
INSTALLATION-STRING-1 


continued 
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A-16 


ALGOL 
Value 


. Pascal/RPG Mnemonic 
INSTSTR2 
INSTSTR3 
INSTSTR4 
INSTHEX1 
INSTHEX2 
INSTLINK 
QDEPTH 
MSGCOUNT 
LASTRESP 
AGGRRESP 
STATS 
DATE 
TIME 
MAXUSRCT 
CURUSRCT 
LSN 
MIXNMBRS 
VIRTTERM 
SCREENSZ 
LANGUAGE 
CONVEN 


COBOL74 Name 
INSTALLATION-STRING-2 
INSTALLATION-STRING-3 
INSTALLATION-STRING-4 
INSTALLATION-HEX-1 
INSTALLATION-HEX-2 
INSTALLATION-DATA-LINK 
QUEUE-DEPTH 
MESSAGE-COUNT 
LAST-RESPONSE 
AGGREGATE-RESPONSE 
STATISTICS 

DATE 

TIME 
MAXIMUM-USER-COUNT 
CURRENT-USER-COUNT 
LSN 

MIXNUMBERS 

VIRTUAL TERMINAL 
SCREENSZ 

LANGUAGE 
CONVENTION 


. Table A-5. Service Function Security Category Values and Mnemonics (cont.) 
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Defining Input Header Information 


Table B-1 lists the words, the COMS field names, and the Language field names 
associated with standard COMS input header layout. 
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Table B-1. 


COMS Field Name 
Program Designator 


Function Index 


Function Status 


Usercode Designator 


Security Designator 


(FIELDS) 


43:16 (not used) 


31:02 (reserved) 


29:01 Transparent 


28:01 VT Flag 


27:04 (reserved) 


input Header Information 


Language Field Name 
PROGRAMDESG 


- 3.6 COBOL74 CD: SYMBOLIC QUEUE 


FUNCTIONINDEX 
3.6 COBOL74 CD: SYMBOLIC SUB-QUEUE-1 


FUNCTIONSTATUS 


USERCODE 
3.6 COBOL74 CD: SYMBOLIC SUB-QUEUE-2 


SECURITYDESG 
3.6 COBOL74 CD: SYMBOLIC SUB-QUEUE-3 


FIELDS 


TRANSPARENT 


VTFLAG 


continued 
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Table B-1. Input Header Information (cont.) 


COMS Field Name 


23:23 (not used) . 


00:01 (reserved) 


Timestamp 


Station Designator 


Text Length 


(not used) 


Status Value 


Message Count 


Restart 


Agenda Designator 


SDF Plus Information 


SDF Plus Form Record 


SDF Plus Transaction 


Retries to Go 


(not used) 


Language Field Name 


TIMESTAMP 
3.6 COBOL74 CD: MESSAGE TIME 


STATION 
3.6 COBOL74 CD: SYMBOLIC SOURCE 


TEXTLENGTH 
3.6 COBOL74 CD: TEXT LENGTH 


STATUSVALUE | 
3.6 COBOL74 CD: STATUS KEY 


MESSAGECOUNT 
3.6 COBOL74 CD: MESSAGE COUNT 


RESTART 


AGENDA 


SDFINFO 
SDFFORMRECNUM 
SDFTRANSNUM 


RETRIESLEFT 


continued 
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Table B-1. Input Header Information (cont.) 


COMS Field Name Language Field Name 


Conversation Area ALGOL: (user-defined) 
COBOL74: CONVERSATION AREA 
Pascal: CONVERSATIONAREA 
RPG: CONVERSATION 
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Defining Output Header Information 


Table B-2 lists the words, the COMS field names, and the Language field names 
associated with standard COMS output header layout. 


Table B-2. Output Header Information 


COMS Field Name Language Field Name 
Destination Count DESTCOUNT 
3.6 COBOL74 CD: DESTINATION COUNT 


Text Length TEXTLENGTH 
3.6 COBOL74 CD: TEXT LENGTH 


Status Value STATUSVALUE 
3.6 COBOL74 CD: STATUS KEY 


(FIELDS) FIELDS 


47:16 Carriage 
Control 


47:08 (Advancing 
Amount) 


39:01 (not used) 


38:01 (Before or 
After) 


37:03 (Action) 
34:01 (New Page) 


33:01 (No Carriage 
Return) 


32:01 (No Line 
Feed) 
31:05 (reserved) 


26:01 Transparent TRANSPARENT | 


25:01 VI Flag VTFLAG 


continued 
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COMS Header Layout 


Table B-2. Output Header Information (cont.) 


Word COMS Field Name Language Field Name 


24:01 Delivery CONFIRMFLAG 
Confirmation Flag 


23:24 Delivery CONFIRMKEY 
Confirmation Key , 


4 Destination DESTINATIONDESG 
Designator 


3.6 COBOL74.CD: DESTINATION TABLE 


5 Next Input Agenda NEXTINPUTAGENDA 
Designator 
6 (TOGGLES) TOGGLES 


47:45 (not used) 
02:01 Casual Output CASUALOUTPUT 


01:01 Set Next Input SETNEXTINPUTAGENDA 
Agenda 


00:01 Retain RETAINTRANSACTIONMODE 
Transaction Mode 


7-10 (not used) 
11 Agenda Designator AGENDA 
12 SDF Information SDFINFO 
13 7 SDF Plus Form SDFFORMRECNUM 
Record 


continued 
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COMS Header Layout 


Table B—-2. Output Header Information (cont.) 


COMS Field Name Language Field Name 
SDF Plus Transaction SDFTRANSNUM 


Retries to Go RETRIESLEFT 


(not used) 


Conversation Area ALGOL (user-defined) 
COBOL74: CONVERSATION AREA 
Pascal: CONVERSATIONAREA 
RPG: CONVERSATION 
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Appendix C 
Sample COBOL74 Programs 


This appendix provides three sample COBOL74 programs that demonstrate 


e Using a default agenda with minimal features of the COMS direct-window interface 
e Applying a Screen Design Facility (SDF) form as a processing item to messages . 
e Routing by trancode with different SDF forms for sending and receiving messages 


(A COMS interface to SDF is not currently available through the ALGOL, Pascal, or 
RPG programming languages.) 


To write programs with messages routed by COMS, you must be familiar with COMS as 
a whole. You should understand the information presented in this guide and be familiar 
with the information explained in the following documents: 

e The COMS Configuration Guide 

e The COMS Operations Guide 

e The SDF Operations and Programming Guide 

e The COBOL ANSI-74 Reference Manual, Volumes 1 and 2 


Also, if you plan to use SDF extensively, you should know how to create SDF forms and 
formlibraries before you try to write application programs that use them. 


The first sample program in this appendix, Program 1, shows a simple way to use the 
COMS direct-window interface with a default agenda. The second sample program 
modifies the first by adding an SDF form as a processing item. Program 3 modifies the 
second example by implementing trancode routing and a second SDF form. 


The actual program listings for each sample program are proceeded by the following: 


e Apbrief introductory description of the program 
e Adiscussion of the COMS and SDF entities you must define for the program 
e Guidelines for the declarations and routines used in the program 


e Procedures for running and terminating the program 


Note: The procedures for running and terminating the sample programs 
assume that your station has been defined to COMS. 


5 
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Program 1: Using a Default Agenda 


This is an echo program that returns a duplicate of each message a station sends. To use 
this program, you need to create a default agenda that specifies the echo program as the 
destination for messages received and sent. 


Defining COMS Entities for Program 1 


Because this is a direct-window program, it must be initiated by COMS. You cannot 
start this program with the CANDE RUN or EXECUTE commands. To cause COMS 
to initiate the program and route messages for it, use the COMS Utility menus or 
commands, as described in the COMS Configuration Guide, to define the following 
COMS entities in the order presented: 


1. Definea window that this program will access. Supplying notify-on and notify-open 


text for the window might help you understand how the program operates within 
COMS. 


Define the program name to COMS. 


Define a default agenda whose destination is this program, and associate this agenda 
with the window you defined in step 1. 


(You do not need to define any processing items for use with this agenda, because 
Program 1 does not apply processing items to the messages that it sends or. 
receives.) 


Declarations and Routines for Program 1 


Program 1 shows the following basic, minimal declarations and routines needed for an 
application program that uses COMS direct windows: 


A message area F 

An input header 

An output header 

A routine that initializes the program to run under COMS 

A main processing loop that executes the SEND and RECEIVE statements 


The first three components are explained in Section 3, “Communicating with COMS 
through Direct Windows.” A main processing loop that goes to end of job (EOJ) if the 
Status Value field of the input header contains a value of 99 is considered a standard 
termination routine for a program using the direct-window interface. Minimally, you 
should use the COBOL74 MOVE statement to specify values for the following fields of 
the output header before executing the SEND statement: 


1. Move the value 1 to the Destination Count field of the output header to specify a 


single destination for outgoing messages. 


2. Move a value (a station or program designator) into the Destination field of the 


C-2 


output header to indicate a particular destination for outgoing messages. 
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3. Move a value representing the length of the output message text into the Text 
Length field of the output header. 


Using Program 1 


After you have defined the required entities with the COMS Utility, you can start 
Program 1 by issuing an ?0N <window name> command from your station, followed by 
the first input message. 


You can start the program automatically, without entering an input message, if you 
specify a notify-open action for the window. You can specify a notify-open action either 
with text or without text. Ifyou do not specify text, COMS sends a message with a 
length of 0 (zero) to the program when you open the window. 


Use the ?DISABLE PROGRAM <program name> command to terminate Program 1. 
If you want the program to terminate automatically, specify a termination time limit 
other than 0 (zero) when you use the COMS Utility to define the program. You can 
also use the COMS ?WINDOWS, ?CLOSE, ?SUSPEND, and ?7RESUME commands to 
manipulate this program. Refer to the COMS Operations Guide for more information 
about these COMS commands. 

Program 1 Listing 


Following is the listing of Program 1: 
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IDENTIFICATION DIVISION. 
ENVIRONMENT DIVISION. - 
DATA DIVISION. 
WORKING-STORAGE SECTION. 


81 COMS~NAME -PIC X(®72). 
@1 COMS-MESSAGE-AREA. 
@5 COMS-MESSAGE PIC X(1928). 


COMMUNICATION SECTION. 

INPUT HEADER COMS-IN. 

OUTPUT HEADER COMS-OUT. 
PROCEDURE DIVISION. 
CONTROLLER-SECTION SECTION 1. 
CONTROLLER. 

PERFORM START-UP-SECTION. 

PERFORM PROCESS-IT-SECTION 

UNTIL STATUSVALUE OF COMS-IN = 99. 
STOP RUN. 


START-UP-SECTION SECTION 59. 
START-UP. 
MOVE ATTRIBUTE NAME OF ATTRIBUTE EXCEPTIONTASK OF 
ATTRIBUTE EXCEPTIONTASK OF MYSELF TO COMS-NAME. 
CHANGE ATTRIBUTE TITLE OF "DCILIBRARY" 
TO COMS-NAME. 
PROCESS-IT-SECTION SECTION 1. 
PROCESS-IT. 
RECEIVE COMS-IN MESSAGE. INTO COMS-MESSAGE. 
IF STATUSVALUE OF COMS-IN NOT = 99 
IF NOT FUNCTIONSTATUS OF COMS-IN < 9 
MOVE 1 TO DESTCOUNT OF COMS-OUT 
MOVE STATION OF COMS-IN TO DESTINATIONDESG OF COMS-OUT 
MOVE TEXTLENGTH OF COMS-IN TO TEXTLENGTH OF COMS-OUT 
SEND COMS-OUT FROM COMS-MESSAGE 
GO TO PROCESS-IT. 
END-OF-JOB. 
STOP RUN. 


Program 2: Using an SDF Form Processing Item 


This program is a modification of Program 1. It shows how to use a COMS agenda to 
apply an SDF form as a processing item to messages received and sent. The program 
shows the most basic COMS and SDF concepts and COBOL74 language extensions 
needed to write a COBOL74 program that uses a COMS direct window and an SDF 
form. 


Defining COMS and SDF Entities for Program 2 


Before writing a program like this, you must have created a form in a formlibrary using 
screens in the SDF system. For this particular program, you can use default values in 
the fields of the formlibrary Definition screen and the Form Definition screen, except for 
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library sharing. Specifically, you must choose SHAREDBYRUNUNIT for the Library 
Sharing option on the formlibrary Definition screen. (Refer to the A Series Screen 
Design Facility (SDF) Operations and Programming Guide for detailed instructions on 
creating SDF entities.) 


Next, you must define the COMS and SDF entities that are needed to perform © 
direct-window message processing with an SDF form. Use the COMS Utility menus or 
commands to define the following entities in the order presented: 


1. Define a COMS library and assign the name of the formlibrary generated by SDF as 
the library title. Include the appropriate usercode and pack as part of the title. 


2. Define a COMS processing item that is associated with the formlibrary already 
defined. The Actual Name attribute should be PROC_ITEM. The library name 
should be the name of the library that you defined in step 1. 


3. Define a COMS processing-item list that includes the processing item already 
defined. 


4. Define a COMS direct window. 
5. . Define the COMS program name. 


Define a default output agenda that names the direct window already defined and 
the destination program. Place the processing-item list you defined in the agenda. 


Declarations and Routines for Program 2 
Like Program 1, Program 2 requires the following minimal declarations and routines: 


e Amessage area 

e Aninput header 

e Anoutput header 

e Aroutine that initializes the program to run under COMS 


Additionally, Program 2 can use the same standard COMS termination routine as 
Program 1. 


Program 2, however, invokes the SDF formlibrary, and the SDF form is applied to 
messages as a processing item. To incorporate an SDF form into this scheme, use the 
following declarations and routines, in the order presented: 


1. Use the SPECIAL-NAMES paragraph in the Configuration Section to specify the 
program name and the dictionary that stores the SDF formlibrary. 
2. Declare the SDF formlibrary as a level 01 record, using the following syntax: 


@1 <generated formlibrary name> FROM DICTIONARY. 


This declaration invokes the formlibrary. The compiler copies in all the record 
descriptions for the formlibrary, causing a break in the sequence range of the 
program. 


3. Declare a level 01 record for the Agenda Name using the following data type: 
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Agenda Name: PIC X(17) VALUE "<agenda name>". 
4. Declare a level 01 record for the Agenda Designator using the following data type: 
Agenda Designator: PIC S9(11) USAGE BINARY. 


5. In the initialization routine, obtain an agenda designator by calling the 
GET_DESIGNATOR_USING_NAME service function. Be sure to include the 
service function call after the ENABLE INPUT statement. 


6. Inthe main processing loop, let the RECEIVE statement use the SDF form asa 
message area with the following syntax: | 


RECEIVE <input header name> MESSAGE INTO <SDF form name>. 


7. Move the agenda designator into the Agenda Designator field of the output header 
to specify the message destination for the SEND statement. 


8. Move the FORM-KEY, which identifies the desired SDF form to the SDF system, 
into the Conversation Area field of the output header. 


9. Let the SEND statement use the SDF form as the message area with the following 
syntax: 


SEND <output header name> FROM <SDF form name>. 


Using Program 2 


When COMS responds to the ?O0N <window name> command by placing the station in 
the direct window specified in the command, you must transmit an initial message from 
the station in order to receive the first SDF form. Once you receive the SDF form, the 
program echoes each message you transmit, because the destination defined for the 
agenda is the echo program itself. 


Use the ?DISABLE PROGRAM <program name> command or a termination time 
limit other than 0 (zero) to terminate Program 2. 


When you use a program that invokes SDF forms, you might need to recompile the 
program whenever you regenerate the SDF formlibrary, if you have made changes to the 
formlibrary. 


Program 2 Listing 


Following is the listing of Program 2: 
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$SET LIST WARNSUPR 
IDENTIFICATION DIVISION. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SPECIAL-NAMES. 
DICTIONARY IS "SCREENDESIGN", 
PROGRAM-NAME IS "ECHOWITHSDF". 
DATA DIVISION. 
WORKING-STORAGE SECTION. 


@1 COMS-NAME PIC X(972). 

@1 SDF formlibrary FROM DICTIONARY. 
KEKKKREKEREEKEKRKEKEKEREKKEREKREKEKEKRRREREEKERKREKRRKEREKEREKERERKERKKE 
* THE FOLLOWING LINES OF CODE ARE GENERATED BY THE SYSTEM: * 


KEKKKKRKREERKEEKRKERERERREEKEERERERRKKRERERERERRERRRERRKERERERERREKEK 


*--DICTIONARY 

*--DICTIONARY FORMLIST< SDF formlibrary >. 
* — SDFFORM. 

x ACTION PIC X(19). 

= CHOICE PIC X(2@). 

= MESSAGEAREA PIC X(3@). 


KKEKKKKEKERERKEKEKEEREREKEREREKRERRRERRERRREKEEKERKRERERREKERKERERREREER 


+ + F£ F + F 


$1 SDF-AGENDA-NAME PIC X(17) VALUE “SDFAGENDA". 
77 SDF~AGENDA-DESIGNATOR USAGE REAL. 
77 SDF-CALL-ERROR PIC $9(11) USAGE BINARY. 


COMMUNICATION SECTION. 
INPUT HEADER COMS-IN. 
OUTPUT HEADER COMS-OUT 
CONVERSATION AREA. 
@2 COMS-OUT-CONVERSATION REAL. 
PROCEDURE DIVISION. 
CONTROLLER-SECTION SECTION 1. 
CONTROLLER. . 
PERFORM START-UP-SECTION. 
PERFORM PROCESS-IT-SECTION 
UNTIL STATUSVALUE OF COMS-IN = 99. 
STOP RUN. 
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START-UP-SECTION SECTION 59. 
START-UP. 
MOVE ATTRIBUTE NAME OF ATTRIBUTE EXCEPTIONTASK OF 
ATTRIBUTE EXCEPTIONTASK OF MYSELF TO COMS-NAME. 
CHANGE ATTRIBUTE TITLE OF "DCILIBRARY" 
TO COMS-NAME. 
ENABLE INPUT COMS-IN KEY "ONLINE". 
CALL "GET _DESIGNATOR_USING NAME IN DCILIBRARY" 
USING SDF-AGENDA-NAME 
sVALUE AGENDA 
, SDF-AGENDA-DESIGNATOR. 
GIVING SDF-CALL-ERROR. 
PROCESS-IT-SECTION SECTION 1. 
PROCESS-IT. | 
RECEIVE COMS-IN MESSAGE INTO SDFFORM. 
IF STATUSVALUE OF COMS-IN NOT = 99 _ 
IF NOT FUNCTIONSTATUS OF COMS-IN < @ 
MOVE 1 TO DESTCOUNT OF COMS-OUT 
MOVE STATION OF COMS~-IN TO DESTINATIONDESG OF COMS-OUT 
MOVE TEXTLENGTH OF COMS-IN TO TEXTLENGTH OF COMS-OUT 
MOVE SDF-AGENDA-DESIGNATOR TO STATUSVALUE OF COMS-OUT 
MOVE FORM-KEY (SDFFORM) TO COMS-OUT-CONVERSATION 
SEND COMS-OUT FROM SDFFORM. 
-END-OF-JOB. 


Program 3: Routing by Trancode 


This echo program is a modification of Program 2. It shows routing by trancode and the 
use of two SDF forms as processing items. 


Defining COMS and SDF Entities for Program 3 


Before writing a program like this, you must have created two forms in a formlibrary 
using screens in the SDF system. To use routing by trancode with an SDF form, you 
must specify the following values when completing these SDF screens: 


1. On the formlibrary Definition screen, make the following choices: 
e Choose SHAREDBYRUNUNIT for the Library Sharing option. 
e Answer Y, for yes, to the question, “Will this library process forms based on 
message keys?” 
e Answer Y, for yes, to the question, “Will the Module Index be used for routing 
with COMS interface?” 


2. After creating the forms with the Form Definition screen, use the Additional Field 
Definition screen to define a message key for each form. For each form you are 
defining, you need to define a message key at the same offset and with the same 
length. (Use the first field on each form for the message keys.) You also need to 
define default values for the message keys. 
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3. The message key in SDF corresponds to the trancode in COMS. The entity referred 
to as the COMS index or module index in SDF corresponds to the module function 
index (MFI) in COMS. The FORM-KRY used in a program like Program 3 identifies 
to SDF which form the program is invoking. 


Next, all of the COMS entities defined for Program 2 need to be defined for Program 3. 
These include the COMS library, a processing item and processing-item list, a direct 
window, the program name, and an agenda. 


Program 3 can use the same window as Program 2, but it requires a separate agenda, 
processing item, and processing-item list. Also, you must define two trancodes for 
routing the two SDF forms to the program. 


Use the COMS Utility to assign the window and agenda to each trancode. You also need 
to assign an MFI, which is an integer value associated with the trancode used in the 
application program to reference the trancode. 


Declarations and Routines for Program 3 


All the guidelines for program declarations and routines presented for Programs 1 and 
2 apply to Program 3 as well. However, the clause SAME RECORD AREA has been 
added to the level 01 record declaration for the name of the generated formlibrary. Ina 
program that uses more than one SDF form, the SAME RECORD AREA clause makes 
every form a redefinition of the other forms. 


In Program 3, the second form description for an SDF form redefines the form 
description for the first SDF form. Since the program does not know what kind of 
message it will receive, it must be able to redefine the form that serves as the message 
area. 


In the main processing loop, an IF-THEN-ELSE statement is used to determine which. 
SDF form to invoke based on the MFI value. After the program receives a message, 
COMS places a value for the MFI (if defined) into the COMS-in-Function-Index field of 
the input header. In the case of Program 3, entering one of the two defined trancodes 
from the terminal causes COMS to place the appropriate MFI value in the Function 
Index field of the input header. The program can then execute the corresponding branch 
of the IF-THEN-ELSE statement. . 


Before executing the SEND statement, the program moves the FORM-KEY that 


references the required SDF form into the Conversation Area field of the output header. 
The following syntax should be used: 


MOVE FORM-KEY(SDFFORM) TO COMS-OUT-CONVERSATION 


Using Program 3. 
When COMS responds to the 7ON <window name> command by placing the station in 


that direct window, enter from your terminal one of the trancodes you defined to invoke 
one of the two SDF forms used in this example. 
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Use the 2?DISABLE PROGRAM <program name> command or specify a termination 
time limit other than 0 (zero) for the program to terminate Program 3. 


Note: When using a program that invokes SDF forms, you must recompile 
the program whenever you regenerate the SDF formlibrary. 


Program 3 Listing 
Following is a listing of Program 3: 


$SET LIST WARNSUPR 
IDENTIFICATION DIVISION. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SPECIAL-NAMES. 
DICTIONARY IS "SCREENDESIGN", 
PROGRAM-NAME IS "“ECHOWITHSDFTBR". 
DATA DIVISION. 
WORKING-STORAGE SECTION. 
G1 COMS-NAME PIC X(@72). 
G1 SDF form library FROM DICTIONARY; SAME RECORD AREA. 


KEKKEERKKEKRKEKEKKEREEKEKKEKEKKREKEKREREKEREKREEREEEKERRERREREREREREKEREREEE 


* THE FOLLOWING LINES OF CODE ARE GENERATED BY THE SYSTEM: * 
KEEKKEKKREKKEEKRKKEKERKKEEREEEREKEREKREEREREREREREREREERERERKERRREKREKK 
--DICTIONARY 
--DICTIONARY FORMLIST < SDFFORM LIBRARY >. 
SDFFORM. 
ACTION PIC X(19). 
CHOICE PIC X(20). 
MESSAGEAREA PIC X(30). 
SDFFORM2 REDEFINES SDFFORM. 
ACTION2 PIC X(18). 
NAME2 PIC X(39). 
TITLE2 PIC X(20). 


KREKKEKKKEKEKRRKRERRERREERKERKREREKERERERERRREEREKRREREERERKEERERRREREREEE 


+ + + FF + F F FF F 
* + + + + FF F HF HF F 


‘$1 SDF-AGENDA-NAME ~ PIC X(17) VALUE "SDFTBRAGENDA". 
77 SDF-AGENDA-DESIGNATOR _ USAGE REAL. 
77 SDF-CALL-ERROR PIC S9(11) USAGE BINARY. 


COMMUNICATION SECTION. 
INPUT HEADER COMS-IN. 
OUTPUT HEADER COMS-OUT 
CONVERSATION AREA. 
G2 COMS-OUT-CONVERSATION REAL. 
PROCEDURE DIVISION. 
CONTROLLER-SECTION SECTION 1. 
CONTROLLER. 
PERFORM START-UP-SECTION. 
PERFORM PROCESS-IT-SECTION 
UNTIL STATUSVALUE OF COMS-IN = 99. 
STOP RUN. 
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START-UP-SECTION SECTION 59. 
START-UP. 
MOVE ATTRIBUTE NAME OF ATTRIBUTE EXCEPTIONTASK OF 
ATTRIBUTE EXCEPTIONTASK OF MYSELF TO COMS-NAME. 
CHANGE ATTRIBUTE TITLE OF "DCILIBRARY" 
TO COMS-NAME. 
ENABLE INPUT COMS-IN KEY "ONLINE". 
CALL "GET _DESIGNATOR_USING NAME" IN DCILIBRARY" 
USING SDF-AGENDA-NAME 
» VALUE (AGENDA) 
» SDF-~AGENDA-DESTIGNATOR 
GIVING SDF-CALL-ERROR. 


PROCESS-IT-SECTION SECTION 1. 
PROCESS-IT. 
RECEIVE COMS-IN MESSAGE INTO SDFFORM. 
IF STATUSVALUE OF COMS-IN NOT = 99 
IF NOT FUNCTIONSTATUS OF COMS-IN < @ 
MOVE 1 TO DESTCOUNT OF COMS-OUT 
MOVE STATION OF COMS-IN TO DESTINATIONDESG OF COMS-OUT 
MOVE TEXTLENGTH OF COMS-IN TO TEXTLENGTH OF COMS-OUT 
MOVE SDF-AGENDA-DESIGNATOR TO STATUSVALUE OF COMS-OUT 
IF FUNCTIONINDEX OF COMS-IN = 1 THEN 
MOVE FORM-KEY(SDFFORM) TO COMS-OUT-CONVERSATION 
SEND COMS-OUT FROM SDFFORM , 
ELSE 
IF FUNCTIONINDEX OF COMS-IN = 2 THEN 
MOVE FORM-KEY(SDFFORM2) TO COMS-OUT-CONVERSATION 
SEND COMS-OUT FROM SDFFORM2. 
END-OF-JOB. 
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This appendix provides two sample processing items and the set of global declarations 
that these processing items require. All these declarations should precede the code for 


the processing items, and therefore are listed first. The two sample processing items, 


TPTOMARC and STATUS LINE, are described later in this appendix. 


Commentary within the code provides additional explanation. 


Global Declarations 


There are six sets of global declarations that do the following: 


The code in the following pages of this section corresponds to the global declarations. 


Set the TITLE parameter. 

Define the input header parameters. 
Define the output header parameters. 
Define the STATE parameters. 
Define the result action values. 


Define the function values. 


Setting the TITLE Parameter 


The following code sets the TITLE parameter, which is used by the TPTOMARC 
processing item. Note the sequence of steps described in the commentary. | 
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$ SET SHARING = SHAREDBYALL 
BEGIN 


oe 


First, the code declares a library that is used to call COMS 
service functions. 


oe oe oe 


LIBRARY COMS_LIB(LIBACCESS = BYTITLE); 


The code below declares the GET_NAME_USING DESIGNATOR 
service function entry point. 


de & & 


INTEGER PROCEDURE GET_NAME_USING DESIGNATOR(STA_DESG, STA_NAME) ; 
VALUE STA_DESG; 
REAL STA_DESG: 

EBCDIC ARRAY STA_NAME[8]; 

LIBRARY COMS LIB; 


The following code declares the GET DESIGNATOR_USING NAME service 
function entry point. 


ow & & & 


INTEGER PROCEDURE GET DESIGNATOR USING NAME(STA_NAME, MNEMONIC, 
STA_DESG); 
VALUE MNEMONIC; 
REAL STA_DESG 
EBCDIC ARRAY STA_NAME[Q]; 
LIBRARY COMS LIB; 
DEFINE STATION MNEMONIC = 1#; 


x 


de cd ¥& 3 


Next, the code declares the global data structures and the locks and 
lock routines to manage them. ' 


BOOLEAN 
TITLE_SET; % This value is TRUE if the title of COMS LIB 
% has been set. 
EBCDIC ARRAY % Holds title of COMS LIB. 


TTL[@:299] ; 
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The following example has only one lock, the TITLE lock (TTL). 
When the title of COMS LIB is set, the TITLE lock must be locked. 


de de o&& 3 


REAL 
TTL_OWNER, % The PROCESSID of the owner of the TITLE lock. 
TTL_NUM; % The PROCESSID of the last requestor of the TITLE 
% lock. 


EVENT 
TTL_EVENT3; % The event to PROCURE/LIBERATE if there is lock 
% contention for the TITLE lock. 


The following define causes the TITLE lock to be acquired. The 
define uses a modified form of FIBLOCK, an operating 

system lock type used by the logical 1/0 to lock files. 

The modifications of FIBLOCK reduce overhead with high lock 
contention. 


To ensure that locking TTL and identifying the owner of TTL 
either both occur or neither occur, the code disables external 
interrupts. 


NOTE 


The following defines use the DMALGOL 
constructs DISALLOW and ALLOW to enter 
and exit contro] state. If the defines 
are used, modify them only with extreme | 
care. 


dS de WH BW LH BH DH HW H GE HK BW BW KH KH HK LH & SO 


DEFINE 
ACQUIRE _TTLLOCK = 
BEGIN 
DISALLOW; 
IF READLOCK(PROCESSID, TTL_NUM) NEQ @ THEN 
DO 
-PROCURE(TTL_EVENT) 
UNTIL 
READLOCK(-1, TTL_NUM) = @; 
TTL_OWNER:=PROCESSID; 
ALLOW; 
END#, 
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s€ 3 Be HS HS HL 


ov & © & 


Og 


The following define relinquishes the TITLE lock. The define 
also disables external interrupts so that either of the 
following occurs: 


1. The TITLE lock is relinquished and the owner of the TITLE 
lock is reset. 


2. The TTL lock is not relinquished and the owner of the TITLE 
lock is not reset. 


~ RELINQUISH _TTLLOCK = 


oe xe oe oe oe oe oe oe oe oe oe oe oe oe x we oe oe aA oe oe oe oe oe oe oe 


BEGIN 
DISALLOW; 


‘TTL_OWNER:=9; 


IF READLOCK(@, TTL_NUM) NEQ PROCESSID THEN 
LIBERATE(TTL_EVENT) ; 

ALLOW: 

END#, 


The PROTECTION HEADING define should be invoked once in every 
block that needs to acquire the TITLE lock. This. define 
declares a dummy label and an EPILOG procedure, then invokes 
the ACQUIRE_TTLLOCK define. Therefore, this define must come 
after all declarations and before all statements in a block. 


The label is used to prevent programming errors by requiring 
the scope of the lock protection to be identified. The EPILOG 
procedure is used to relinquish the TITLE lock if it has been 
acquired. 


The purpose of locking the TITLE lock in this way is to allow 
the COMS programs that invoke processing items to be 
discontinued while they are in processing item code. As . 

a result, the lock does not remain locked. This procedure is 
used to keep global data structures from being left in 
half-changed states. 


If a lock is acquired, the owner can always be identified. If 
a program that is discontinued (DSed) is the owner of the lock, 
its EPILOG procedure will relinquish the lock. If a program 
left TTL locked, the next program to attempt to acquire the 
TITLE lock would have its processing suspended until the 
program is discontinued. 
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PROTECTION HEADING = 
LABEL PROTECTION_LABEL; 
EPILOG PROCEDURE PROTECT MARC; 
BEGIN 
DISALLOW; 
IF TTL_OWNER = PROCESSID THEN 
RELINQUISH _TTLLOCK; 
ALLOW; 
END PROTECT MARC; 
ACQUIRE_TTLLOCK #, 


“we 


ve 


The following is the dummy label declared in the 
PROTECTION HEADING define. It is used to minimize programming 
errors by identifying the scope of the lock protection. 


se ve oe 


PROTECTION TRAILER = 
PROTECTION LABEL: #3 


Since TITLE_SET is never reset once it is TRUE, SET_TITLE need 
never be called if TITLE_SET is TRUE. 


% & & & 


DEFINE 
CHECK_TITLE = IF NOT TITLE_SET THEN 
SET_TITLE#; 
PROCEDURE SET TITLE; 
BEGIN 


The SET_TITLE procedure is called only if TITLE_SET is FALSE. 
This procedure uses the PROTECTION HEADING and 

PROTECTION TRAILER defines to ensure proper access to the 
global TITLE lock and the TITLE_SET global variables. The 
function of this procedure is to set the title of COMS LIB to 
the correct name. 


de d& dA Be De WH SC oO 


PROTECTION HEADING; 


The TITLE_SET Boolean must be checked under the lock. This 
checking closes the timing hole caused when multiple stacks 
call SET_TITLE simultaneously. 


de dg & o& © 


IF NOT TITLE_SET THEN 
BEGIN 
REPLACE TTL BY MYSELF.EXCEPTIONTASK.EXCEPTIONTASK.NAME3 
COMS_LIB.TITLE:=HEAD(STRING(TTL, 72), NOT 48°26"); 
TITLE_SET:=TRUE; 
END; 

PROTECTION TRAILER; 

END OF SET TITLE; 
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Defining Input Header Parameters 


The input header parameters are used for the ACCEPT, ENABLE INPUT, ENABLE 
INPUT TERMINAL, DISABLE INPUT TERMINAL, and RECEIVE statements. These 
parameters are used by the TPTOMARC processing item. The following code defines 
input header parameters: | 


COMS_IN_RST_LOC 
COMS_IN_CD_SIZE(S) 


CD_IN[19]#, ! 
(STATE_CONVINX(S)) #3 


DEFINE 
COMS_IN_PROGRAM = CD_IN[9]#, 
COMS_IN FUNCTION INDEX = CD_IN[1]#, 
COMS_IN_USERCODE = CD_IN(2]#, 
COMS_IN SECURITY DESG = CD_IN[3]#, 
COMS_IN DATE = CD_IN[4]#, 
COMS_IN_ TIMESTAMP = CD_IN[5]#; 
COMS_IN STATION | = CD_IN[6]#, 
COMS_IN_TEXT_LENGTH = CD_IN[7]#; 
COMS_IN_END KEY = CD_IN[8]#, 
COMS_IN_STATUS_KEY = CD_IN[9]#, 


Defining Output Header Parameters 


The output header parameters are used for sending data. These parameters are used 
by the STATUS _LINE processing item. The following code defines output header 
parameters: 


DEFINE 


COMS_OUT_COUNT 
COMS_OUT_TEXT_LENGTH 
COMS_OUT_STATUS_KEY 
COMS_OUT_DESTIN ERROR 
COMS_OUT_DESTINATION 
COMS_OUT_CONV_TSTAMP 


CD_OUT[O]#, 
CD _OUT[1]#, 
CD_OUT[2]#, 
CD_OUT[3]#, 
CD_OUT[4]#, 


% SDF FORM-KEY timestamp. 
CD_OUT[STATE_CONVINX (STATE) ]#, 

% MARC MultiLingual System 
. % (MLS) message number. 
CD_OUT[STATE_CONVINX (STATE) +1] #5 


COMS_OUT_CONV_MSGN 
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Defining the STATE Parameters 


The following code defines the STATE parameters, which is used by both processing 
items: 


DEFINE 


Sw 


6 [47:24] % Available to the user. 


se 
se 


6 [23:24] 6 Reserved for COMS use. 


ow 


1 
G 


STATE_IN_OUTF [99:01] #, 


Output header 
Input header 


oe 


STATE_OUT (S) 
STATE_IN (S) 


BOOLEAN(S) .STATE_IN_OUTF#, 
NOT STATE_OUT(S)#, 


STATE_CONVINXF [13:86]#, % Index to conversation area. 


STATE_CONVINX (S) 


(S) .STATE_CONVINXF#, 


STATE_MSG_LOCF 


= [15:82]#, % Valid data locations: 
% @ = USER_TEXT 
% 1 = TEXT_1 
% 2 = TEXT 2 
% 3 = Invalid value 


STATE_MSG_LOC (S) S.STATE_MSG_LOCF#; 


Defining the Result Action Values 


The following code defines the result action values of the STATUS_LINE processing 


item: 

DEFINE 
CONTINUEV = O#, 
STOPV = l#, 
STOP_RETURNV = 2#; 


Defining the Function Values 


The following code defines the function values used by Menu-Assisted Resource Control 
(MARC). These values are required by the TPTOMARC processing item. 


DEFINE 
FUNC_NORMALMSGV = O#, % A normal message (for example, No ?). 
FUNC_CONTROLMSGV =-l#; % A 


control message (for example, A ?). 
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_TPTOMARC Processing Item 


The TPTOMARC processing item translates the station designator associated with a 
message from a program in a direct window into a designator that MARC recognizes. As 
a result, programs in direct windows can send input messages to MARC, and MARC will 
accept them. (MARC discards messages with designators that it does not recognize.) 
The following code defines the TPTOMARC processing item: 


REAL PROCEDURE TPTOMARC (STATE, CD_IN, USER_TEXT, TEXT_1, 
TEXT_2, OUTPUT PROC); 


REAL STATE;3 

ARRAY CD_IN[@]; 

EBCDIC ARRAY USER_TEXT, TEXT_1, TEXT_2[@]; 

REAL PROCEDURE OUTPUT_PROC(STATE, CD, TEXT_1, TEXT_2);3 
REAL STATE; 
ARRAY CD[]; 
EBCDIC ARRAY TEXT_1, TEXT_2[@]; 


FORMAL3 
BEGIN 
EBCDIC ARRAY REFERENCE 
MSGIN[@] , Points to valid data. 


STA_NAME[Q] ; % Points to scratch data area. 


DEFINE 
CAND (A, B) = (IF (A) THEN (B) ELSE FALSE)#; 


IF CAND(STATE_IN(STATE) , 
COMS_IN_FUNCTION_INDEX 
COMS_IN_FUNCTION_INDEX 


Hy 


FUNC_NORMALMSGV OR 
FUNC_CONTROLMSGV) THEN 


tt 


The code above accepts input messages that are either normal 
input or control input. Output messages and messages with 
other function values are ignored. 


de de 3 & 


IF COMS_IN PROGRAM ISNT @ THEN % Checks whether input 
% is not from a station. 
BEGIN 


In the code above, the message has been rerouted by some 
other direct-window program. If more security is required, 
check the value of COMS_IN PROGRAM here, and write a ‘ 
procedure to provide the desired control. 


de o& co & & of 
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CASE STATE_MSG_LOC(STATE) OF 
BEGIN 
G: 
MSGIN:=USER_TEXT3; 
STA_NAME:=TEXT_1; 
ae 
MSGIN:=TEXT_1; 
STA_NAME:=TEXT 2; 
2: 
MSGIN:=TEXT_ 2; 
STA_NAME:=TEXT_1; 
END; 


oe 


MSGIN now references the text of the valid data and 
STA_NAME references an unused, scratch data area; for 
example, TEXT_1 or TEXT 2. 


ve & 


we 


oe 


STA_NAME is resized to contain the largest possible 
station name. 


xe 


oe 


IF SIZE(STA_NAME) LSS 308 THEN 
RESIZE(STA_NAME, 399); 


Ordinarily, control messages are only identified by the 
NDLII. However, a processing item can change a message into 
a control message (and vice versa) by changing the function 
value in the Input CD. TPTOMARC looks at the first 
character of input. If the input begins with a question 
mark (?), the message is changed to a control message. This 
procedure allows programs to send control messages as well 
as noncontrol messages to MARC. 


de de de de SEO Se SS GO HH 


IF MSGIN[@] = "2?" THEN 

COMS_IN_FUNCTION_INDEX:=FUNC_CONTROLMSGV 

ELSE | 
COMS_IN_FUNCTION_INDEX:=FUNC_NORMALMSGV ; 


Sample Processing Items 


Before the program calls COMS service functions, the 
following code insures that the title of COMS_LIB has 
been set. 


BX S SL 


CHECK_TITLE; 


The next two steps are essential. 


First, the code calls GET_NAME_ USING DESIGNATOR to 
translate the station designator to the station name 
it represents. 


dw & && & H& & oC 


REPLACE STA_NAME BY " " FOR 5 WORDS; 
GET_NAME_USING DESIGNATOR(COMS_IN STATION, 
STA_NAME) ; 


Second, the code calls GET _DESIGNATOR_USING NAME to change 
the station name back to a station designator. Because a 
call is made on top of a MARC stack, the station designator 
returned represents dialogue 1 of the MARC window for the 
station name. 


ve & HS & & & & 


GET_DESIGNATOR_USING_NAME(STA_NAME,STATION_MNEMONIC, 
COMS~IN-STATION) ; 
END; 
END OF TPTOMARC; 


STATUS LINE Processing Item 


D-10 


The STATUS_LINE processing item handles MARC error messages sent in response to 
direct-window input from ET, MT, or TD terminals. The processing item causes the error 
message to be displayed on the status line of the terminal. As a result, the screen of the 
user’s screen is not disturbed by error messages received by the terminal. 
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Note that MARC uses the second word of the conversation area 
(COMS OUT_CONV_MSGN) as follows: 


e Ifthe value COMS_OUT_CONV_MSGN ranges from 0 through 65535, then the 
value is the MultiLingual System (MLS) message number of the last MLS message 
MARC formatted into the output. 


e Ifthe value of COMS OUT_CONV_MSGN ranges from -65535 through 
-1, then the value is a valid MLS message number of the last MLS message 
MARC formatted. However, the MLS message either was not found in the 
OUTPUTMESSAGE array or was not in the original language requested. This code 
is provided to show how to use an output processing item to monitor proper message 
translations. 


e Any other value for COMS_OUT_CONV_MSGN means that MARC did not 
format an MLS message number into the output. MARC places the value 
4“000000100000” (representing ~65536) into COMS_OUT_CONV_MSGN to 
represent an invalid value. 
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- The following code defines the STATUS _LINE processing item: 


REAL PROCEDURE STATUSLINE(STATE, CD_OUT, USER_TEXT, TEXT_1, 


TEXT_2, OUTPUT PROC) ; 


REAL STATE; 

ARRAY CD_OUT[9]; 

EBCDIC ARRAY USER_TEXT, TEXT_1, TEXT 2[9]; 

REAL PROCEDURE OUTPUT PROC(STATE, CD, TEXT_1, TEXT 2); 
REAL STATE; : 
ARRAY . CD[8]; 

EBCDIC ARRAY TEXT_1, TEXT 2[9]; 


FORMAL; 
BEGIN 
DEFINE 
DC1V = 48"11"#, % Blind transmission for 
ET, MT, and TD terminals. 
ESCV = 48"27"#, % Escape character for 
ET, MT, and TD terminals. 
HOMEV = 48"3C"#, % Home character for ET, MT, and TD 


terminals. 
STATUS _LINE_SZ = 66#, 


d& d& d& de of oo oh 


on the status line. 


LAST_WORD = (((STATUS_LINE_SZ+38)DIV 6)-1)#; 
REAL 
MSGN, % MLS message number. 


Maximum number of characters allowed 


OUTPUT _MSG_LN; % Size of text placed on the status line. 


EBCDIC ARRAY REFERENCE 
INP_DATA[] 
OUT DATA[Q] ; 

REAL ARRAY REFERENCE 
ROUT DATA [8]; 

IF STATE_OUT(STATE) THEN 
BEGIN 


ignored. 


dH & de 3 


The following code is an output message. Input messages are 
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MSGN:=COMS OUT _CONV_MSGN(STATE) ; 
IF MSGN GEQ 2628 AND MSGN LSS 29@@ THEN 
BEGIN 


oe 


oe 


MSGN contains the MLS message number placed in the output 
conversation area by MARC. 


MSGN values between 2628 and 2986 are used by MARC to 
denote error responses caused by an input to a direct 
window. Following is an example of such a response: 


de s© d& & 


oe oe 


MESSAGE REJECTED, THE PROGRAM IS DISABLED. TEXT = .... 


oe 


CASE STATE_MSG_LOC(STATE) OF 
BEGIN 


% In the following code, the data is in USER_TEXT. This 
% data will be reformatted into TEXT_1. 


INP_DATA:=USER_TEXT; 
OUT_DATA:=TEXT_1; 
STATE_MSG_LOC(STATE) :=1; 


In the following code, the data is in TEXT_1. This 
data will be reformatted into TEXT 2. 


ov de de ce 


INP_DATA:=TEXT_1; 
OUT_DATA:=TEXT_2; 
STATE_MSG_LOC(STATE) :=2; 
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In the following code, the data is in TEXT_2. This 
data will be reformatted into TEXT 1. 


de de de 3 


INP_DATA:=TEXT_2; 
OUT_DATA:=TEXT_13 
STATE_MSG_LOC (STATE) :=1; 

END; % CASE 


oe 


INP_DATA now references the data area containing the valid 
data. OUT_DATA now references an unused scratch area. The 
purpose of this code is to reformat the input message from 
INP_DATA into OUT DATA, and add the appropriate control 
characters. 


de oe 


3 


If OUT_DATA is too small, it is resized. 


ve cv & & 


IF SIZE(OUT_DATA) LSS (STATUS LINE SZ+3@) THEN 
RESIZE(OUT_DATA, STATUS_LINE_SZ+30) ; 


If the error message sent to the terminal is longer than 
the smallest status line of an ET, MT, or TD terminal, the 
message will be truncated. 


oe od & 


OUTPUT_MSG_LN:=MIN(COMS_OUT_TEXT_LENGTH, STATUS LINE_SZ); 


ve 


% The following code reformats the message. 


oe 


REPLACE OUT_DATA[@] BY 


DCIV, Suppresses NDLII editing. 
ESCV, "RS", Writes to the status line. 
"OB", Leaves room for the hexadecimal length 


of the text to be placed on the 
status line. 
Moves actual data. 


dH & dH & LS 


INP_DATA[@] FOR 
OUTPUT_MSG_LN, 

HOMEV, 

ESCV, "W"; 


Leaves cursor in the home position. 
Puts terminal into forms mode. 


oe of 


Cg 
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The following code uses the HEXTOEBCDIC translation table 
to translate the binary value of OUTPUT MSG_LN into its 
2-character EBCDIC representation expressed in hexadecimal 
notation. 


oe ce & 


ce 


xe 


ROUT_DATA (a type-real-array reference variable to 
OUT_DATA) is used to generate the HEX pointer required by 
the HEXTOEBCDIC translation table. 


se oe 


oe 


ROUT_DATA:=OUT_DATA; 

ROUT DATA[LAST WORD] . [47:8] :=OUTPUT_MSG_LN; 

REPLACE OUT_DATA[4] BY POINTER(ROUT_ paste WORD] ,4) 
FOR 2 WITH HEXTOEBCDIC; 


ow 


“we 


The following code updates the length field in the Output 
CD to reflect the edited message. 


oe 


Ng 


COMS_OUT_TEXT_LENGTH:=OUTPUT_MSG_LN+9; 
END; 
END; 
END OF STATUSLINE; 
EXPORT 
STATUSLINE, 
TPTOMARC; 


FREEZE (TEMPORARY) ; 
END. 
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Appendix E 
Sample COBOL74 Processing- 
Item Interface 


Processing items can be written in any programming language that ALGOL can call. 
This appendix provides an example of a COBOL74 program that can be bound to an 
ALGOL shell. Included in the example is a sample Binder program. (For further 
information on Binder programs, see the A Series Binder Programming Reference 
Manual.) 


% The assumption in Binder is that the object for this program unit 
% is titled "OBJECT/COMS /PROCESSINGITEM/ALGOLSHELL". 


“ 


BEGIN 
REAL PROCEDURE PROCESSING ITEM 
(STATE, 
cD, 
USER_DATA, 
TEXT_1, 
TEXT 2, 
OUTPUT PROC) ; 
REAL STATE; 
ARRAY CD [81]; 
EBCDIC ARRAY USER DATA, TEXT_1, TEXT 2 [8]; 
REAL PROCEDURE OUTPUT PROC 
(STATE, 
cD, 
TEXT_1, 
TEXT 2); 
REAL STATE; 
ARRAY CD [8]; 
EBCDIC ARRAY TEXT 1, TEXT_2 OE 
FORMAL; 


8600 0650-000 


Sample COBOL74 Processing-Item Interface 


BEGIN % PROCESSING_ITEM 


program as a parameter. 


de de Be Ge BE Be GB SO BW BE BE BE BDO SH So KH VL 


procedures. 


REAL 
RETURNRESULTREAL, % from the subprogram 


NEWTEXTSIZEREAL, % for resizing of arrays if needed 
QUTPUTPROCRESULTREAL; % result from OUTPUT PROC 


INTEGER 
RETURNRESULT = RETURNRESULTREAL, 
NEWTEXTSIZE = NEWTEXTSIZEREAL, 
OUTPUTPROCRESULT = OUTPUTPROCRESULTREAL3 


9 
% 


PROCEDURE RESIZE _TEXT_1 IF_NEEDED; 
BEGIN % to avoid SEG ARRAY errors: 
IF NEWTEXTSIZE GEQ SIZE (TEXT_1) THEN 
RESIZE (TEXT_1, NEWTEXTSIZE * 2, RETAIN); 
END; 
PROCEDURE RESIZE _TEXT_2_IF_ NEEDED; 
BEGIN % likewise: 
IF NEWTEXTSIZE GEQ SIZE (TEXT_2) THEN 
RESIZE (TEXT_2, NEWTEXTSIZE * 2, RETAIN); 


END; 


Since we cannot declare a typed procedure in COBOL74, we must 
simulate it by passing the result back from the subprogram 

as a parameter local to the shell, and then setting the value of the 
shell (a typed procedure) to the value returned in the parameter. 


This applies as well to calls to OUTPUT_PROC from the COBOL74 
program--we cannot call a typed procedure, so we declare an untyped 
procedure in the shell, and pass the result back to the COBOL74 


Note that external to the COBOL74 program, the parameters are REALs. 
Internally they are integers; hence, the double definition. 


There are two ALGOL procedures declared global to the COBOL74 program 
to resize the text arrays (which can have zero length on entry). 
NEWTEXTSIZE is a parameter used by the subprogram and these two 
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% 

PROCEDURE CALL_OUTPUT PROC; 

BEGIN 

OUTPUTPROCRESULTREAL := OUTPUT_PROC (STATE, CD, TEXT_1, TEXT_2); 
END; 


° 
% 


PROCEDURE SUBP; EXTERNAL; % This is the COBOL74 subprogram 
PROCESSING ITEM EXECUTABLE 

Call the COBOL74 Subprogram: 

SuBP; 


% 
% Set PROCESSING_ITEM.VALUE to the result passed from the 
% COBOL74 subprogram: 


PROCESSING_ITEM := RETURNRESULTREAL3; 


oe 


oe 


END OF PROCESSING_ITEM; 
EXPORT PROCESSING_ITEM; 


“FREEZE (PERMANENT); 


65%6%6%6%6%6%%%e% End of ALGOL host for COBOL74 processing-item subprogram. 


SAMPLE COBOL74 SUBPROGRAM FOR PROCESSING ITEM 


The assumption in BINDER is that the object for this program unit 
is titled "OBJECT/COMS/PROCESSINGITEM/SUBPROGRAM" . 


Note: The COBOL74 subprogram should be declared at LEX LEVEL 4. 


+ + + + & 


$LEVEL = 4 

* 
IDENTIFICATION DIVISION. 
ENVIRONMENT DIVISION. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 


COMS~-STATE, COMS-NEW-TEXT-SIZE, COMS-RETURN-RESULT, 
COMS-OUTPUTPROC-RESULT, COMS-IN-CD-ARRAY, 

COMS-IN-TEXT-1, COMS-IN-TEXT-2, and COMS-USER-DATA are al] 
global to the subprogram and MUST be so declared. 


+ + + + 
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+ + + F F F 


Everything else is local to this subprogram. 

Try to minimize local data to avoid significant 
overhead due to stack building and teardown, since 
the local stack for this program will be built every time 


it is called. 


77 COMS-STATE 

77 COMS-NEW-TEXT-SIZE 

77 COMS-STATE-I-OR-0 

77 ~COMS-STATE-CONV-INX 
77 COMS-STATE-MSG-LOC 

77 COMS-STATE-USER-FIELD 
77 COMS-RETURN-RESULT 


77 COMS-OUTPUTPROC-RESULT PICTURE 


81 COMS~-IN-CD-ARRAY 
03 COMS-IN-PROGRAM 


@3 COMS-IN-FUNCTION-INDEX 


3 COMS-IN-USERCODE 


@3 COMS-IN~SECURITY-DESG 


®3 COMS-IN-DATE 

83 COMS-IN-TIMESTAMP 
@3 COMS-IN-STATION 

83 COMS-IN-TEXT-LENGTH 
@3 COMS-IN-END-KEY 

@3 COMS-IN-STATUS-KEY 
@3 COMS-IN-RST-LOCATOR 


$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 


PICTURE 
PICTURE 
PICTURE 
PICTURE 
PICTURE 
PICTURE 
PICTURE 
PICTURE 
PICTURE 
PICTURE 
PICTURE 


USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 
$9(11) 


66 MARC-MESSAGE-NUMBER RENAMES COMS-IN-STATION. 


@1 COMS-IN-TEXT-1 
81 COMS-IN-TEXT-2 
81 COMS-IN-USER-DATA 
PROCEDURE DIVISION. 


DECLARATIVES. 
CHECK-TEXT-1-SIZE SECTION. 
USE AS GLOBAL PROCEDURE. 
CHECK-TEXT-2-SIZE SECTION. 
USE AS GLOBAL PROCEDURE. 
COMS-OUTPUT-PROC SECTION. 
USE AS GLOBAL PROCEDURE. 
END DECLARATIVES. 


MAIN-SECTION. 
ENTRY-PARAGRAPH. 


IS BINARY 
IS BINARY 


IS BINARY. 
IS BINARY. 
IS BINARY. 
IS BINARY. 


IS BINARY 
IS BINARY 
IS BINARY 


USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 
USAGE 


IS 
iS 
is 
IS 
IS 
ES 
IS 
IS 
IS 
IS 
IS 


PICTURE X(1928) 
PICTURE X(192@) GLOBAL. 


PICTURE 


GLOBAL. 
GLOBAL. 


GLOBAL. 
GLOBAL. 
GLOBAL. 
BINARY. 
BINARY. 
BINARY. 
BINARY. 
BINARY. 
BINARY. 
BINARY. 
BINARY. 
BINARY. 
BINARY. 
BINARY. 


GLOBAL. 


X(1928) GLOBAL. 
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* 


* Split the fields in STATE into separate words so they can be 
* more easily examined/manipulated in the subprogram: 
MOVE @ TO COMS-STATE-I-OR-0, 
COMS-STATE-CONV-INX, 
COMS-STATE-MSG-LOC, 
COMS-STATE-USER-FIELD. 
MOVE COMS-STATE TO COMS-STATE-I-OR-0 [@:9:1]. 
MOVE COMS-STATE TO COMS-STATE-CONV-INX [13:5:6]. 
MOVE COMS-STATE TO COMS-STATE-MSG-LOC [15:1:2]. 
MOVE COMS-STATE TO COMS-STATE-USER-FIELD [47:23:24]. 


+ + 4 


Body of this particular processing item: 


IF COMS-STATE-I-OR-0 > @ 
IF MARC-MESSAGE-NUMBER > 2989 
OR MARC-MESSAGE-NUMBER < 2680 
MOVE 1 TO COMS-RETURN-RESULT 
GO TO RETURN-TO-COMS. 
IF COMS-IN-FUNCTION-INDEX = -1 
MOVE 1 TO COMS-RETURN-RESULT 
GO TO RETURN-TO-COMS. 
IF COMS-IN-FUNCTION-INDEX = 9 
IF COMS-STATE-MSG-LOC = 8 . 
ADD 18, COMS-IN-TEXT-LENGTH GIVING COMS-NEW-TEXT-SIZE 
CALL CHECK-TEXT-1-SIZE 
STRING "?20N CANDE:" DELIMITED BY SIZE, 
COMS-IN-USER-DATA FOR COMS-IN-TEXT-LENGTH 
INTO COMS-IN-TEXT-1 
MOVE -1 TO COMS-IN-FUNCTION-INDEX 
MOVE COMS-NEW-TEXT-SIZE TO COMS-IN-TEXT-LENGTH 
MOVE 1 TO COMS-STATE-MSG-LOC 
ELSE IF COMS-STATE-MSG-LOC = 1 
ADD 18, COMS-IN-TEXT-LENGTH GIVING COMS-NEW-TEXT-SIZE 
CALL CHECK-TEXT-2-SIZE 
STRING "20N CANDE:" DELIMITED BY SIZE, 
COMS-IN-TEXT-1 FOR COMS-IN-TEXT-LENGTH 
INTO COMS-IN-TEXT~-2 
MOVE -1 TO COMS-IN-FUNCTION-INDEX 
MOVE COMS-NEW-TEXT-SIZE TO COMS-IN-TEXT-LENGTH 
MOVE 2 TO COMS-STATE-MSG-LOC 
ELSE IF COMS-STATE-MSG-LOC = 2 
ADD 18, COMS-IN-TEXT-LENGTH GIVING COMS-NEW-TEXT-SIZE 
CALL CHECK-TEXT-1-SIZE 
STRING "20N CANDE:" DELIMITED BY SIZE, 
COMS-IN-TEXT-2 FOR COMS-IN-TEXT-LENGTH 
INTO COMS-IN-TEXT=1 
MOVE -1 TO COMS-IN-FUNCTION-INDEX 
ADD 18 TO COMS-IN-TEXT-LENGTH 
MOVE 1 TO COMS-STATE-MSG-LOC. . 
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+ + + + FF F FE F FF F 4 HF 


Should the user desire to call COMS' OUTPUT PROC: 
1) Make sure the STATE word is restored before calling; 
2) Make sure it is “redistributed" after calling; 
3) Take appropriate action based on output result. 
Example: 


PERFORM COMS-OUTPUT-PARAGRAPH THROUGH 
COMS-OUTPUT-PARAGRAPH~EXIT. 
IF COMS-OUTPUTPROC-RESULT ........- 


COMS -OUTPUT~PARAGRAPH. 
* Rebuild COMS-STATE: 
MOVE COMS-STATE-I-OR-O TO COMS-STATE [@:@:1]. 
MOVE COMS-STATE-CONV-INX TO COMS-STATE [5:13:6]. 
MOVE COMS-STATE-MSG-LOC TO COMS-STATE [1:15:2]. | 
MOVE COMS-STATE-USER-FIELD TO COMS-STATE [23:47:24]. 
* Call ALGOL shell procedure that calls OUTPUT_PROC: 
CALL COMS-OUTPUT-PROC. 
* Redistribute COMS-STATE into local words: 
MOVE @ TO COMS-STATE-I-OR-0, 
COMS-STATE-MSG-LOC, 
COMS-STATE-USER-FIELD. 
MOVE COMS-STATE TO COMS-STATE-I-OR-O [@:9:1]. 
MOVE COMS-STATE TO COMS-STATE-CONV-INX [13:5:6]. 
MOVE COMS-STATE TO COMS-STATE-MSG-LOC [15:1:2]. 
MOVE COMS-STATE TO COMS-STATE-USER-FIELD [47:23:24]. 
COMS -OUTPUT-PARAGRAPH-EXIT. 
EXIT. 


RETURNING TO ALGOL SHELL: 


Particularly in the event you have manipulated the data items 
extracted from COMS-IN-STATE, be sure it is updated before 
returning to the calling ALGOL shell: 


+ + + + F FF F F 


RETURN-TO-COMS. 
MOVE COMS-STATE-I-OR-O0 TO COMS-STATE [@:9:1]. 
MOVE COMS-STATE-CONV-INX TO COMS-STATE [5:13:6]. 
MOVE COMS-STATE-MSG-LOC TO COMS-STATE [1:15:2]. 
MOVE COMS-STATE-USER-FIELD TO COMS-STATE [23:47:24]. 


+ 


Exit to shell: 
EXIT-PARAGRAPH. 


EXIT PROCEDURE. 
ieee END OF COBOL74 SUBPROGRAM 
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SAMPLE WFL SOURCE: 


oe ge de & 


BEGIN JOB PROCESSITEM$ 
CLASS = 16; 
JOBSUMMARY = UNCONDITIONAL; 
COMPILE OBJECT/COMS/PROCESSINGITEM/ALGOLSHELL WITH ALGOL LIBRARY; 
COMPILER FILE CARD (KIND=DISK, 
DEPENDENTSPECS = TRUE, 
TITLE = COMS/PROCESSINGITEM/ALGOLSHELL) ; 
COMPILE OBJECT/COMS /PROCESSINGITEM/SUBPROGRAM WITH COBOL74 LIBRARY; 
COMPILER FILE CARD (KIND=DISK, 
DEPENDENTSPECS = TRUE, 
TITLE = COMS/PROCESSINGITEM/SUBPROGRAM) ; 
COMPILE OBJECT/COMS/PROCESSINGITEM/BOUND WITH BINDER LIBRARY; 
COMPILER FILE CARD (KIND = DISK, 
DEPENDENTSPECS = TRUE, 
TITLE = COMS/PROCESSINGITEM/BOUND) ; 
?END JOB 
%6c625atshatotetesEND OF SAMPLE WFL SOURCE 


% 
% SAMPLE BINDER SOURCE: 

% 

ese 

HOST IS OBJECT/COMS/PROCESSINGITEM/ALGOLSHELL; 

BIND SUBP FROM OBJECT/COMS/PROCESSINGITEM/SUBPROGRAM; 
% 


Correlate the names in the ALGOL shell with those in the 
COBOL74 subprogram: 


Name in ALGOL shell: Name in COBOL74 Subprogram: 
USE STATE FOR COMS~STATE; 
USE RETURNRESULT FOR COMS-RETURN-RESULT ; 
USE OUTPUTPROCRESULT FOR COMS-OUTPUTPROC-RESULT ; 
USE CD FOR COMS-IN-CD~ARRAY ; 
USE TEXT 1 FOR COMS-IN-TEXT-13 
USE TEXT_2 : FOR COMS-IN-TEXT-2; 
USE USER_DATA FOR COMS-IN-USER-DATA3$ 
USE RESIZE _TEXT_1_IF_NEEDED FOR CHECK-TEXT-1-SIZE3$ 
USE RESIZE_TEXT_2 IF_NEEDED FOR CHECK-TEXT-2-SIZE; 
USE CALL_OUTPUT_PROC FOR COMS-OUTPUT-PROC; 
USE NEWTEXTSIZE FOR COMS-NEW-TEXT-SIZE3; 
STOP; 


%%%%%%%%%%%6%%~6% END OF BINDER SOURCE 
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Appendix F 
Service Functions for Previous Releases 


If you have developed your programs using Mark 3.6 or Mark 3.5 COMS, the service 
functions described in this appendix are valid for those programs. These service 
functions cannot be used by either the Pascal or the Report Program Generator (RPG) 
programming languages. 


Programs that use the null character to initialize arrays for entity names, however, must 
be modified to use the space character. When COMS returns an entity name in response 
to a service function call, it uses space characters to blank fill the remainder of the array. 
Thus, programs that initialize and scan for null characters will fail. 


Agenda Designators and Names 


You can use COMS service functions to obtain information on 


e Agenda designators (with GET_AGENDA DESIGNATOR) 
e Agenda names (with GET_AGENDA NAME) 


The following pages describe these service functions. 


Agenda Designators 


The COMS library returns an agenda designator when you pass to the 
GET_AGENDA_DESIGNATOR service function either of the following: 


e Anagenda name with a length of 1 to 17 alphanumeric characters. It is assumed 
that the agenda is defined for the window in which the program is running. 


e Anagenda name, with a length of 1 to 17 alphanumeric characters, and a window 
name, with a length of 1 to 17 alphanumeric characters, separated by the word "OF". . 
This is how a program can reference agendas defined for windows other than the 
window in which the program is running. For example, the following syntax allows a 
program to reference agendas that are related to windows other than the window in 
which the program is running. 


<agenda name> OF <window name> 


Origin of Input Parameter 


Each agenda name is defined with the COMS Utility. To obtain reports about the agenda 
names and other entities defined for your system, refer to the COMS Configuration 
Guide. 
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Programming Requirements 


Table F—1 shows the input parameters you pass to the GET_AGENDA DESIGNATOR 
service function and the output parameters that the COMS library returns. The table 
also provides data types for the parameters in ALGOL and COBOL, and the values that 
can be returned by the service function call. . 


Table F-1. GET_AGENDA_ DESIGNATOR Parameters 
Direction Parameter COBOL Data Type | ALGOL Data Type 
Input to COMS Agenda name COBOL74: Display EBCDIC array 


Output from - Agenda COBOL74: Binary - Integer 
COMS designator 


Output from Function value The function value 0 is returned by the 
COMS GET_AGENDA_DESIGNATOR call if there is an 
invalid agenda name for the window in which 
the program is running. 


For COBOL74, declare each variable as a PIC S9(11) (1-word) field. Declare the binary 
data type shown in Table F-1 at level 77, and the display data types at level 01. 


Examples 
Following are examples of COBOL and ALGOL code for calling the 


GET_AGENDA_DESIGNATOR service function from an application program or an 
agenda processing item: 


COBOL74 


CALL "GET AGENDA DESIGNATOR OF DCILIBRARY" 
USING <agenda name>, 
GIVING <agenda designator>. 


ALGOL 


<agenda designator> := GET_AGENDA_DESIGNATOR 
(<agenda name>) ; 


Agenda Names 


When you pass an agenda designator to the GET_AGENDA_NAME service function, the 
COMS library returns an agenda name with a length of 1 to 17 alphanumeric characters. 
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Origin of Input Parameter 


You can obtain an agenda designator from the GET AGENDA DESIGNATOR service 
function. 


Programming Requirements 


Table F-2 shows the input parameters you pass to the GET_AGENDA_ NAME service 
function and the output parameters that the COMS library returns. The table also 
provides data types for the parameters in ALGOL and COBOL, and the values that can 
be returned by the service function call. 


Table F-2. GET AGENDA_NAME Parameters 


Direction Parameter COBOL Data Type ALGOL Data Type 


Input to COMS Agenda COBOL74: Display Integer 
designator 


Output from Agenda name COBOL74: Display - EBCDIC array 
COMS 


Output from Function value The following function values can be returned by 
COMS the GET_AGENDA_NAME call: 


e j= Noerrors 


e 0 = Invalid designator 


For COBOL74, declare each variable as a PIC $9(11) (1-word) field. Declare the binary 
data type shown in Table F-2 at level 77, and the display data types at level 01. 


Examples 


Following are examples of COBOL and ALGOL code for calling the 
GET AGENDA NAME service function from an application program or an agenda 
processing item: | 


COBOL74 


CALL "GET_AGENDA_NAME IN DCILIBRARY" 
USING <agenda designator>, 
<agenda name>, : 
GIVING <result of GET AGENDA_NAME service function>. 


ALGOL 
<result of GET_AGENDA_NAME service function> ;:= 


GET_AGENDA_NAME (<agenda designator>, 
<agenda name>) ; 
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~Window Designators and Maximum Users 


You can use COMS service functions to obtain information on the following: 


e Window designators (with GET WINDOW DESIGNATOR) 


e The maximum number of users who can access a window at one time (with 
GET_WINDOW_INFO) 


The following pages describe these service functions. 


Window Designators 


F-4 


When a program passes a window name having a length of 1 to 17 alphanumeric 


_ characters to the GET_WINDOW_DESIGNATOR service function, the COMS library 


returns a window designator. 


If a program does not know the name of the window it is associated with, you can place 
an asterisk (*) in the first column of the parameter you pass for the window name. 
COMS will return the window designator for the window associated with the calling 
program. 


Calling the GET WINDOW DESIGNATOR service function is necessary if you want to 
obtain a window designator in order to call the GET_WINDOW_INFO service function. 


Origin of Input Parameter 


A window name is defined with COMS Utility at system-definition time. To obtain 
reports about the window names and other entities defined for your system, refer to the 
COMS Configuration Guide. 


Programming Requirements 


Table F-3 shows the input parameters you pass to the GET_WINDOW_DESIGNATOR 
service function and the output parameters that the COMS library returns. The table 
also provides data types for the parameters in ALGOL and COBOL, and the values that 
can be returned by the service function call. 


Table F-3. GET_WINDOW_DESIGNATOR Parameters 


Direction Parameter COBOL Data Type ALGOL Data Type 
Input to COMS Window name COBOL74: Display EBCDIC array 


Output from Window COBOL74: Binary integer 
COMS : designator 


continued 
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Table F-3. GET_WINDOW_DESIGNATOR Parameters (cont.) 


Direction Parameter COBOL Data Type ALGOL Data Type 


Output from Function value The following function values can be returned by 
COMS the GET_WINDOW_DESIGNATOR call: 


e 0 = Invalid window name 


e Other = Requested window designator 


For COBOL74, declare each variable as a PIC S9(11) (1-word) field. Declare the binary 
data type shown in Table F-3 at level 77, and the display data types at level 01. 


Examples 


Following are examples of COBOL and ALGOL code for calling the 
GET_WINDOW_DESIGNATOR service function from an application program or a 
processing item: 


COBOL74 


CALL "GET_WINDOW_DESIGNATOR IN DCILIBRARY" 
USING <window name>, 
GIVING <window designator>. 


ALGOL. 
<window designator> := GET_WINDOW_ DESIGNATOR 
(<window name>) ; 
Maximum Users of a Window 
When you pass a window designator to the GET_WINDOW_INFO service function, the 
COMS library returns the maximum number of-users that can access the window at a 


particular time. COMS returns this value in the first word of the zero-relative array 
(that is, INFO[0]), which you pass for receiving output. 


Origin of Input Parameter 


You can obtain a window designator by using the window name to call the 
GET_WINDOW_DESIGNATOR service function. 
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Programming Requirements 


Table F—-4 shows the input parameters you pass to the GET_WINDOW_INFO service 
function and the output parameters that the COMS library returns. The table also 
provides data types for the parameters in ALGOL and COBOL, and the values that can 
be returned by the service function call. 


Table F-4. GET _WINDOW_INFO Parameters 


Direction Parameter COBOL Data Type ALGOL Data Type 


input to COMS Window COBOL74: Binary integer 
designator 


Output from Window COBOL74: Binary Integer 


COMS information 


Output from Function value The following function values can be returned by 
COMS the GET_WINDOW_INFO call: 


e 0 = Invalid window name 


e 1=Noerrors 


For COBOL74, declare each variable as a PIC $9(11) (1-word) field. Declare the binary 
data type shown in Table F-4 at level 77, and the display data types at level 01. . 


Examples 


Following are examples of COBOL and ALGOL code for calling the 
GET_WINDOW_INFO service function from an application program or a processing 
item: 


COBOL74 


CALL "GET _WINDOW_INFO IN DCILIBRARY" 
USING <window designator>, 
<window info>, 
GIVING <result of GET_WINDOW_INFO service function>. 


ALGOL 


<result of GET_WINDOW_INFO service function> := 
GET_WINDOW_INFO (<window designator>, 
‘<window info>) ; 
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Data Comm Device-Type Designators and Names 


You can use COMS service functions to obtain information on 
e Data comm device-type designators (with GET DEVICE_DESIGNATOR) 
e Data comm device-type names (with GET DEVICE NAME) 


The following pages describe these service functions. 


| Device-Type Designators 


When you pass a device-type name with a length of 1 to 17 alphanumeric characters 
to the GET_DEVICE_DESIGNATOR service function, the COMS library returns a 
device-type designator. 


Origin of Input Parameter 


Each device-type name is defined with the COMS Utility at system-definition time. To 
obtain reports about the device-type names and other entities defined for your system, 
refer to the COMS Consiguration Guide. 


- Programming Requirements 


Table F-5 shows the input parameter you pass to the GET_DEVICE_DESIGNATOR 
service function and the output parameter that the COMS library returns. The table 
also provides data types for the parameters in ALGOL and COBOL, and the values that 
can be returned by the service function call. 


Table F-5. GET_DEVICE DESIGNATOR Parameters 
Direction Parameter COBOL Data Type ALGOL Data Type 
Input to COMS Device name COBOL74: Binary EBCDIC array 


Output from Window COBOL74: Binary Integer 
COMS information — 


Output from Function value The function value O is returned by the 
COMS GET_DEVICE_DESIGNATOR call if there is an 
invalid device-type name. 


For COBOL74, declare each variable as a PIC $9(11) (1-word) field. Declare the binary 
data type shown in Table F-5 at level 77, and the display data types at level 01. 
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Examples 
Following are examples of COBOL and ALGOL code for calling the 


GET DEVICE DESIGNATOR service function from an application program or an 
agenda processing item: 


COBOL74 


CALL "GET DEVICE DESIGNATOR IN DCILIBRARY" 
USING <device-type name>, 
GIVING <device-type designator>. 


ALGOL 


<device-type designator> := GET DEVICE DESIGNATOR 
(<device-type name>) ; 


Device-Type Names 
| When you pass a device-type designator to the GET DEVICE NAME service function, 


the COMS library returns a device-type name with a length of 1 to 17 alphanumeric 
characters. 


Origin of Input Parameter 
You can obtain a device-type designator from one of three sources: 


e The GET _DEVICE_ DESIGNATOR service function 

e The GET_STATION NAME service function 

e The GET _STATION_ATTRIBUTES service function 

Programming Requirements 

Table F-6 shows the input parameters you pass to the GET_DEVICE_NAME service 
function and the output parameters that the COMS library returns. The table also 


provides data types for the parameters in ALGOL and COBOL, and the values that can 
be returned by the service function call. 
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Table F~6. GET_DEVICE_NAME Parameters 


Direction Parameter COBOL Data Type ALGOL Data Type 


Input to COMS Device-type COBOL74: Binary Integer 
designator 


Output from Device-type name COBOL74: Display EBCDIC array 


COMS 
Output from Function value The following function values can be returned by 
COMS the GET_DEVICE_NAME call: 

e 1 = Noerrors 


e 0 = Invalid designator 


For COBOL74, declare each variable as a PIC $9(11) (1-word) field. Declare the binary 
data type shown in Table F-6 at level 77, and the display data types at level 01. 


Examples 


Following are examples of COBOL and ALGOL code for calling the 
GET_DEVICE_NAME service function from an application program or an agenda 
processing item: 


COBOL74 


CALL "GET_DEVICE_NAME IN DCILIBRARY" 
USING <device-type designator>, 
<device-type name>, 
GIVING <result of GET_DEVICE_NAME service function>. 


ALGOL 
<result of GET_DEVICE_NAME service function> := 


GET_DEVICE_NAME (<device-type designator>, 
<device-type name>) ; 


Program Designators and Names 


You can use COMS service functions to obtain information on 


¢ Program designators (with GET PROGRAM DESIGNATOR) 
e Program names (with GET PROGRAM NAME) 
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The following pages describe these service functions. 


Program Designators 


F—10 


When you pass a program name with a length of 1 to 17 alphanumeric characters to the 
GET_PROGRAM_DESIGNATOR service function, the COMS library returns a program 
designator. 


If you place an asterisk (*) in the first column of the parameter you pass for the program 
name, then COMS returns a program designator for the calling program. A processing 
item can call the GET PROGRAM DESIGNATOR service function to determine which 
program is calling it. 


Origin of Input Parameter 
A program name is defined with the COMS Utility at system-definition time. To obtain 


reports about the program names and other entities defined for your system, refer to the 
COMS Configuration Guide. 


Programming Requirements 


Table F-7 shows the input parameters you pass to the GET PROGRAM DESIGNATOR 
service function and the output parameters that the COMS library returns. The table 


‘also provides data types for the parameters in ALGOL and COBOL, and the values that 


can be returned by the service function call. 


Table F-7.. GET_PROGRAM_DESIGNATOR Parameters 


Direction Parameter COBOL Data Type ALGOL Data Type 
Input to COMS Program name COBOL74: Display EBCDIC array 


Output from Program COBOL74: Binary Integer 


COMS designator 


Output from Function value The function value O is returned by the 
COMS GET_PROGRAM_DESIGNATOR call if there is an 
invalid program name. 


For COBOL74, declare each variable as a PIC $9(11) (1-word) field. Declare the binary 
data type shown in Table F-7 at level 77, and the display data types at level 01. 


Examples 


Following are examples of COBOL and ALGOL code for calling the 


_GET_PROGRAM_DESIGNATOR service function from an application program or a 


processing item: 
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COBOL74 
CALL "GET _PROGRAM_ DESIGNATOR IN DCILIBRARY" 


USING <program name>, 
GIVING <program designator>. 


ALGOL | 
<program designator> := GET _PROGRAM DESIGNATOR 
(<program name>) ; 
Program Names 
When you pass a program designator to the GET PROGRAM NAME service function, 


the COMS library returns a program name, with a length of 1 to 17 alphanumeric 
characters, and the program-security designator. 


Origin of Input Parameter 
You can obtain a program designator from either of the following sources: 


e The COMS-in-Program field of the input CD in an application program 
e The GET PROGRAM DESIGNATOR service function 


Programming Requirements 


Table F-8 shows the input parameters you pass to the GET_PROGRAM_NAME service 
function and the output parameters that the COMS library returns. The table also 
provides data types for the parameters in ALGOL and COBOL, and the values that can 
be returned by the service function call. 


Table F-8. GET _PROGRAM_NAME Parameters 


Direction Parameter COBOL Data Type ALGOL Data Type 


input to COMS Program - COBOL74: Binary Integer 
designator . 


Output from Program-security : COBOL74: Binary _ Integer 
COMS designator 


Output from Program name COBOL74: Display EBCDIC array 
COMS 


continued 
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Table F-8. GET_PROGRAM_NAME Parameters (cont.) 


Direction Parameter COBOL Data Type ALGOL Data Type 


Output from Function value The following function values can be returned by 


COMS the GET_PROGRAM_NAME call: 


e 1 = Noerrors 0 = Invalid designator 


For COBOL74, declare each variable as a PIC S9(11) (1-word) field. Declare the binary 
data type shown in Table F-8 at level 77, and the display data types at level 01. 


Examples 


Following are examples of COBOL and ALGOL code for calling the 
GET_PROGRAM_ NAME service function from an application program or an agenda 
processing item: 


COBOL74 


CALL "GET_PROGRAM NAME IN DCILIBRARY" 
USING <program designator>, 
<program-security designator>, 
<program name>, ; 
GIVING <result of GET_PROGRAM NAME service function>. 


ALGOL 


<result of GET PROGRAM NAME service function> := 
- GET_PROGRAM_NAME (<program designator>, 
<program-security designator>, 
<program name>) ; 


Security and Usercodes 


F-12 


The most basic unit of security for COMS is the security category or security level. Up 
to 32 security categories can be defined, although the maximum number of categories for 
a list is limited to the number of defined categories. The categories can be combined in 

a security-category list. Each station and each usercode is assigned a security-category 
list. Therefore, the terms station security and usercode security tell you which security 
categories are valid for a station or usercode, respectively. 


However, each trancode can be assigned only one security category, so that station 


security or usercode security tells you which trancodes are valid for the station or 
usercode. 
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One additional COMS security structure is called session security. This is the 
intersection of the valid security categories for a particular usercode and station. 


You can use COMS service functions to obtain information on 


e Program-security designators (with the service function 


GET PROGRAM SECURITY DESIGNATOR) 


e Security-category designators (with the service function 
GET_SECURITY_CATEGORY_DESIGNATOR) 


e Station-security designators (with the service function 
GET_ STATION. SECURITY_DESIGNATOR) 


e Usercode designators (with the service function GET _USER_DESIGNATOR) 


e Usercode names and usercode-security designators (with the service function 
GET_USER) 


e Usercode security-category-list designators (with the service function 
GET_USER_SECURITY_DESIGNATOR) 


In addition, you can use the TEST_SECURITY_CATEGORY service function to test the 
security category of various designators. 


The following pages describe these service functions. 


Program Security Designators 
When you pass a program designator to the service function called 


GET_PROGRAM_SECURITY_DESIGNATOR, the COMS library returns a designator 
that represents the valid security-category list associated with that program. 


Origin of Input Parameter 
You can obtain a program designator from either of the following sources: 


e The COMS-in-Program field of the input CD in an application program 
e The GET PROGRAM DESIGNATOR service function 


Programming Requirements 


Table F-9 shows the input parameters you pass to the GET_PROGRAM _SECURITY_ 
DESIGNATOR service function and the output parameters that the COMS library 
returns. The table also provides data types for the parameters in ALGOL and COBOL, 
and the values that can be returned by the service function call. . 
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Table F-9. GET PROGRAM_SECURITY_DESIGNATOR Parameters 


Direction Parameter . COBOL Data Type ALGOL Data Type 


Input to COMS Program COBOL74: Display Integer 
designator 


Output from Program-security COBOL74:Binary Integer 
COMS designator 


Output from Function value The function value 0 is returned by the 
COMS GET_PROGRAM_SECURITY_DESIGNATOR call 
: if there is an invalid security category. 


For COBOL74, declare each variable as a PIC S9(11) (1-word) held. Declare the binary 
data type shown in Table F-9 at level 77. 


Examples 


Following are examples of COBOL and ALGOL code for calling the 
GET_PROGRAM_SECURITY_ DESIGNATOR service function from an application 
program or an agenda processing item: 


COBOL74 


CALL "GET_PROGRAM_SECURITY DESIGNATOR IN DCILIBRARY" 
USING <program designator>, 
GIVING <program-security designator>. 


ALGOL 


<program-security designator> := 
GET_PROGRAM_SECURITY_DESIGNATOR 
(<program designator>) ; 


Security-Category Designators 


F-14 


When you pass a security-category name with a length of 1 to 17 alphanumeric 
characters to the service function called GET_SECURITY_CATEGORY_DESIGNATOR, 
the COMS library returns a security-category designator. 


Origin of Input Parameter 
Each security-category name is defined with the COMS Utility at system-definition time. 


To obtain reports about the security-category names and other entities defined for your 
system, refer to the COMS Configuration Guide. 
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Programming Requirements 
Table F-10 shows the input parameters you pass to the GET SECURITY CATEGORY. 
DESIGNATOR service function and the output parameters that the COMS 


library returns. The table also provides data types for the parameters in ALGOL and 
COBOL, and the values that can be returned by the service function call. 


Table F-10. GET_SECURITY_CATEGORY_DESIGNATOR Parameters 


Direction Parameter COBOL Data Type ALGOL Data Type 


Input to COMS Security category COBOL74: Binary Integer 


Output from Program-security COBOL74: Binary Integer 
COMS designator 


Output from Function value The function value 0 is returned by the 
COMS GET_SECURITY_CATEGORY_DESIGNATOR call 
if there is an.invalid security category. 


For COBOL74, declare each variable as a PIC $9(11) (1-word) field. Declare the binary 
data type shown in Table F-10 at level 77, and the display data types at level 01. 


Examples 


Following are examples of COBOL and ALGOL code for calling the 
GET_SECURITY_CATEGORY DESIGNATOR service function from an application 
program or an agenda processing item: 


COBOL74 


$1 <security-category name> PIC X(8@). 
77 <security-category designator> PIC $9(11) BINARY. 
MOVE <payroll manager> TO <security-category name>. 
CALL "GET_SECURITY_CATEGORY_DESIGNATOR 

IN DCILIBRARY" 

USING <security-category name>, 

GIVING <security-category designator>. 
IF <security-category designator> = @ 

DISPLAY "Invalid security-category name". 
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ALGOL 


EBCDIC ARRAY <security-category name> [8:79]; 
INTEGER <security-category designator>; 
INTEGER PROCEDURE GET SECURITY CATEGORY DESIGNATOR 
(<security-category name>) ; 
LIBRARY DCILIBRARY; 


REPLACE <security-category name> [9] BY 
<payroll manager>; 

<security-category designator> := 
GET_SECURITY_CATEGORY_DESIGNATOR 
(<security-category name>) ; 

IF <security-category designator>= 9 THEN 
DISPLAY ("Invalid security-category name"); 


Station-Security Designators 
When you pass a station designator to the service function called 


GET_STATION SECURITY DESIGNATOR, the COMS library returns a 
designator that represents the security-category list associated with the station. 


Origin of Input Parameter 

You can obtain a station designator from either of the following sources: 

© The COMS-in-Station field of the input CD in an application program 

e TheGET STATION DESIGNATOR service function 

Programming Requirements 

Table F~11 shows the input parameters you pass to the GET STATION SECURITY _ 
DESIGNATOR service function and the output parameters that the COMS library 


returns. The table also provides data types for the parameters in ALGOL and COBOL, 
and the values that can be returned by the service function call. 


Table F-11. GET _STATION_SECURITY_DESIGNATOR Parameters 


Direction Parameter ‘COBOL Data Type ALGOL Data Type 
input to COMS Station designator COBOL74: Binary 


Output from Station-security COBOL74: Binary 
COMS designator 


continued 
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Table F-11. GET_STATION_SECURITY_DESIGNATOR Parameters (cont.) 


Direction Parameter COBOL Data Type ALGOL Data Type 


Output from Function value The function value 0 is returned by the 
COMS GET_STATION_SECURITY_DESIGNATOR call if 
there is an invalid designator. 


For COBOL74, declare each variable as a PIC S9(11) (1-word) field. Declare the binary 
data type shown in Table F-11 at level 77. 


Examples 


Following are examples of COBOL and ALGOL code for calling the 
GET_STATION_SECURITY_DESIGNATOR service function from an application 
program or an agenda processing item: 


COBOL74 


CALL "GET _STATION_SECURITY_ DESIGNATOR 
IN DCILIBRARY" 
USING <station designator>, 
GIVING <station-security designator>. 


ALGOL 


<station-security designator> := 
GET_STATION_SECURITY_DESIGNATOR 
(<station designator>) ; 


Usercode Designators 
When you pass a usercode name with a length of 1 to 17 alphanumeric characters to the 


GET_USER_DESIGNATOBR service function, the COMS library returns a usercode 
designator. 


Origin of Input Parameter 
Each usercode name is defined with the COMS Utility at system-definition time. To 


obtain reports about the usercode names and other entities defined for your system, 
refer to the COMS Configuration Guide. 


Programming Requirements 


Table F—12 shows the input parameters you pass to the GET_USER_DESIGNATOR 
service function and the output parameters that the COMS library returns. The table 
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also provides data types for the parameters in ALGOL and COBOL, and the values that © 
can be returned by the service function call. 


Table F-12. GET_USER_DESIGNATOR Parameters 
Direction Parameter COBOL Data Type ALGOL Data Type 
Input to COMS Usercode name COBOL74: Display EBCDIC array 


Output from Usercode COBOL74: Binary Integer 
COMS designator 


Output from Function value The function value O is returned by the 
COMS GET_USER_DESIGNATOR call if there is an 
invalid usercode. 


For COBOL74, declare each variable as a PIC $9(11) (1-word) field. Declare the binary 
data type shown in Table F-12 at level 77, and the display data types at level 01. 


Examples 


Following are examples of COBOL and ALGOL code for calling the 
GET_USER_DESIGNATOR service function from an application program or an agenda 
processing item: 


COBOL74 — 


CALL "GET_USER_DESIGNATOR IN DCILIBRARY" 
USING <usercode name>, 
GIVING <usercode designator>. 


ALGOL 


<usercode designator> := GET_USER_DESIGNATOR 
(<usercode name>) ; 


Usercode Names and Security Designators 


F~18 


When you pass a usercode designator to the GET_USER service function, the COMS 
library returns a usercode name, with a length of 1 to 17 alphanumeric characters, and a 
usercode-security designator. 


If the GET_USER_ DESIGNATOR service function receives a designator corresponding 
to the superuser usercode, the GET_USER_DESIGNATOR service function returns a 
name of 17 blanks. 


If the GET_USER_DESIGNATOR service function receives a name consisting of 17 
blanks, then the GET_USER_DESIGNATOR service function returns the superuser 


8600 0650-000 


Service Functions for Previous Releases 


designator. For more detailed information on the superuser usercode and superuser 
designator, refer to the Security Administration Guide. 


Origin of Input Parameter 
You can obtain a usercode designator from either of the following sources: 


e The COMS-in-Usercode field of the input CD in an application program 
e The GET_USER_ DESIGNATOR service function 


Programming Requirements 


- Table F-13 shows the input parameters you pass to the GET_USER service function and 
the output parameters that the COMS library returns. The table also provides data 
types for the parameters in ALGOL and COBOL, and the values that can be returned by 
the service function call. 


Table F-13. GET_USER Parameters 


Direction Parameter COBOL Data Type ALGOL Data Type 


Input to COMS Usercode COBOL74: Binary Integer 
designator 


Output from Usercode name COBOL74: Display EBCDIC array 


COMS 


Output from Usercode-security COBOL74: Binary Integer 
COMS designator 


Output from Function value The function value O is returned by the 
COMS GET_USER call if there is an invalid designator. 


For COBOL74, declare each variable as a PIC S9(11) (1-word) field. Declare the binary 
data type shown in Table F-13 at level 77, and the display data types at level 01. 


Examples 


Following are examples of COBOL and ALGOL code for calling the GET_USER service 
function from an application program or an agenda processing item: 


COBOL74 


CALL "GET_USER IN DCILIBRARY" 
USING <usercode’ designator>, 
<usercode-security designator>, 
<usercode name>, 
GIVING <result of GET_USER service function>. 
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ALGOL 


<result of GET_USER > service function> := 
GET_USER (<usercode designator>, 
<usercode-security designator>, 
<usercode name>) ; 


Usercode Security-Category-List Designators 


F-20 


When you pass a usercode designator to the service function called . 
GET_USER_SECURITY_ DESIGNATOR, the COMS library returns a designator that 
represents the security-category list associated with the usercode. 


Origin of Input Parameter 
You can obtain a usercode designator from either of the following sources: 


e The COMS-in-Usercode field of the input CD in an application program 
e The GET_USER_DESIGNATOR service function 


Programming Requirements 


Table F-14 shows the input parameters you pass to the GET_USER_SECURITY_DESIGNATOR 
service function and the output parameters that the COMS library returns. The table 

also provides data types for the parameters in ALGOL and COBOL, and the values that 

can be returned by the service function call. 


Table F-14. GET_USER_SECURITY_DESIGNATOR Parameters 


Direction Parameter COBOL Data Type ALGOL Data Type 


Input to COMS Usercode COBOL74: Binary Integer 
designator 


Output from Usercode-security COBOL74: Binary . integer 
COMS designator 


Output from - Function value The function value 0 is returned by the 
COMS GET_USER_SECURITY_DESIGNATOR call if 
there is an invalid designator. 


For COBOL74, declare each variable as a PIC $9(11) (1-word) field. Declare the binary 
data type shown in Table F-14 at level 77. 
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Examples 


Following are examples of COBOL and ALGOL code for calling the 
GET_USER_SECURITY_DESIGNATOR service function from an application program 
or an agenda processing item: 


COBOL74 


CALL "GET_USER_SECURITY_DESIGNATOR 
IN DCILIBRARY" 
USING <usercode designator>, 
GIVING <usercode-security designator>. 


ALGOL 


<usercode-security designator> := 
GET_USER_SECURITY_DESIGNATOR 
(<usercode designator>) ; 


Security-Category Testing 


You can use the TEST_SECURITY_CATEGORY service function to test the security 
category of designators for stations, usercodes, or sessions. 


When you pass a security-category designator and a security designator (a designator 
that represents the valid security categories for a station, a usercode, or a session) to this 
service function, the COMS library returns a function value that tells you whether the 
security categories represented by the designator are valid for the station, usercode, or 
session. 


Origin of Input Parameters 


A security-category designator can be obtained from the 
GET_SECURITY_CATEGORY_DESIGNATOR service function. 


A station-security designator can be obtained from the 
GET _STATION_SECURITY_DESIGNATOR service function. 


A usercode-security designator can be obtained from the 
GET_USER_SECURITY_DESIGNATOR service function. 


A session-security designator can be obtained from the COMS-in-Security-Desg field of 
the input CD in an application program. | 

Programming Requirements 

Table F-15 shows the input parameters you pass to the TEST_SECURITY_CATEGORY _ 
service function and the output parameters that the COMS library returns. The table 


also provides data types for the parameters in ALGOL and COBOL, and the values that 
can be returned by the service function call. 
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Table F-15. TEST SECURITY_CATEGORY Parameters 


Direction Parameter COBOL Data Type ALGOL Data Type 


Input to COMS Security-category COBOL74: Binary Integer 
designator 


Output from Security-category COBOL74: Binary Integer 
COMS test 


Output from Function value - The following function values can be returned by 
COMS the TEST_SECURITY_CATEGORY call: 
e 1 = Valid category 


e 0 = Invalid category 


For COBOL74, declare each variable as a PIC S9(11) (1-word) field. Declare the binary 
data type shown in Table F-15 at level 77. 


Examples 


Following are examples of COBOL and ALGOL code for calling the 
TEST _SECURITY_CATEGORY service function from an application program or an 
agenda processing item: 


COBOL74 


CALL "TEST_SECURITY_CATEGORY IN DCILIBRARY" 
USING <security designator>, | 
<security-category designator>, 
GIVING <result of TEST SECURITY CATEGORY 
service function>. 


ALGOL 


<result of TEST_SECURITY_CATEGORY service function> := 
TEST_SECURITY_CATEGORY (<security designator>, 
<security-category designator>) ; 


Station Information 


You can use the COMS service functions to obtain information on 


e Station attributes (with GET_STATION_ATTRIBUTES) 
e Station designators (with GET STATION_DESIGNATOR) 
e Station lists (with GET STATION LIST) _ 
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e Station-list designators (with GET_STATION_LIST_DESIGNATOR) 
e Station names (with GET STATION NAME) 


The following pages describe these service functions. 


Station Attributes 


When you pass a station designator to the GET STATION_ATTRIBUTES service 
function, the COMS library returns the following information: 


e A logical station number (LSN). If this number is 0, then the station is disconnected. 
e Adevice designator. 

e A station-security designator. © 

e Avirtual terminal. 


e Ascreen size. 

Origin of Input Parameter 

You can obtain a station designator from either of the following sources: 

e The COMS-in-Station field of the input CD in an application program 

e The GET STATION _DESIGNATOR service function 

Programming Requirements 

Table F-16 shows the input parameters you pass to the GET_STATION_ATTRIBUTES 
service function and the output parameters that the COMS library returns. The table 


also provides data types for the parameters in ALGOL and COBOL, and the values that 
can be returned by the service function call. 


Table F-16. GET_STATION_ATTRIBUTES Parameters 
Direction Parameter COBOL Data Type ALGOL Data Type 
Input to COMS Station designator COBOL74: Binary 


Output from LSN COBOL74: Binary 
COMS 


Output from Device designator COBOL74: Binary 
COMS , 


Output from | Station-security COBOL74: Binary 
COMS designator 


continued 


8600 0650-000 | F-23 


Service Functions for Previous Releases 


Table F-16. GET_STATION_ATTRIBUTES Parameters (cont.) 


Direction Parameter COBOL Data Type | ALGOL Data Type 


Output from Virtual terminal COBOL74: Binary Integer 
COMS 


Output from Screen size COBOL74: Binary Integer 
COMS 


Output from Function value The following function values can be returned by 
COMS the GET_STATION_ATTRIBUTES call: 


e 1 = Noerrors 
e 0 = One of the following has occurred: 
- An invalid designator was used 


- The station was no longer logged on to 
COMS 


For COBOL74, declare each variable as a PIC $9(11) (1-word) field. Declare the binary 
data type shown in Table F—-16 at level 77.. 


Examples 


Following are examples of COBOL and ALGOL code for calling the - 
GET_STATION ATTRIBUTES service function from an application program or an 
agenda processing item: 


COBOL74 


CALL "GET_STATION ATTRIBUTES IN DCILIBRARY" 
USING <station designator> 
<device designator> 
<LSN> 
<station-security designator> 
<virtual terminal> 
<screen size> 
GIVING <result of GET_STATION ATTRIBUTES 
service function> 


ALGOL 


<result of GET_STATION_ATTRIBUTES service function> := 
GET_STATION_ATTRIBUTES (<station designator>, | 

<device designator>, <LSN>, <virtual terminal>, 

<screen size>, <station-security designator>) ; 
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Station Designators 


When you pass a valid station name (with a length of 1 to 255 alphanumeric characters) 
to the GET STATION DESIGNATOR service function, the COMS library returns a 
station designator. 


Origin of Input Parameter 


Each station name is defined with the COMS Utility at system-definition time. To obtain 
reports about the station names and other entities defined for your system, refer to the 
COMS Configuration Guide. 


Programming Requirements 


Table F-17 shows the input parameters you pass to the GET STATION DESIGNATOR 
service function and the output parameters that the COMS library returns. The table 
also provides data types for the parameters in ALGOL and COBOL, and the values that 
can be returned by the service function call. | 


Table F-17. GET_STATION_DESIGNATOR Parameters 


Direction Parameter COBOL Data Type ALGOL Data Type 
Input to COMS Station name COBOL74: Display EBCDIC array 


Output from Station designator COBOL74: Binary | Integer 


COMS 


Output from Function value The function value 0 is returned by the 
COMS GET_STATION DESIGNATOR call if there is an 
invalid station name. 


For COBOL74, declare each variable as a PIC $9(11) (1-word) field. Declare the binary 
data type shown in Table F-17 at level 77, and the display data types at level 01. 


_ Examples 


Following are examples of COBOL and ALGOL code for calling the 
GET STATION DESIGNATOR service function from an application program or an 
agenda processing item: 


COBOL74 


CALL "GET_STATION_ DESIGNATOR IN DCILIBRARY" 
USING <station name>, 
GIVING <station designator>. 
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ALGOL 


. “station designator> := 


Station 
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GET_STATION_DESIGNATOR (<station name>) ; 


Lists 


When you pass a station-list designator to the GET_STATION_LIST service function, 
the COMS library returns an array of designators that represent the stations included in 
the station list. Each element in the array is 1 word (6 bytes). 


Origin of Input Parameter 


You can obtain a station-list designator by caine the GET_STATION __ LIST | DESIGNATOR 
service function. 


Programming Requirements 


Table F-18 shows the input parameters you pass to the GET_STATION LIST service 
function and the output parameters that the COMS library returns. The table also 
provides data types for the parameters in ALGOL and COBOL, and the values that can 
be returned by the service function call. 


Table F-18. GET_STATION_LIST Parameters 


Direction | Parameter COBOL Data Type ALGOL Data Type 


Input to COMS Station-list COBOL74: Binary integer 
designator 


Output from Station list COBOL74: Binary Integer array 
COMS ; 


Output from Function value The following function values can be returned by 
COMS the GET_STATION_LIST call: 


e 1 through n = The number of designators 
returned in list ; 


e 0 = Invalid station-list designator 


For COBOL74, declare each variable as a PIC $9(11) (1-word) field. Declare the 


station-list designator in Table F-18 at level 77. Declare the station list at level 01 using 
binary (for COBOL74). The size of the station list should be large enough to hold the 
largest station list requested. 
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Examples 


Following are examples of COBOL and ALGOL code for calling the 
GET STATION _LIST service function from an application program or an agenda 
processing item: 


COBOL74 


CALL "GET_STATION LIST IN DCILIBRARY" 
USING <station-list designator>, 
<station list> 
GIVING <result of GET_STATION_LIST 
service function> 


ALGOL 


<result of GET_STATION LIST service function> := 
GET_STATION LIST (<station-list designator>, 
<station list>); 


- Station-List Designators 


When you pass a station-list name with a length of 1 to 17 alphanumeric characters to 
the service function called GET_STATION_LIST_DESIGNATOR, the COMS library 
returns a designator representing the station list. 


Origin of Input Parameter 


A station-list name is defined with the COMS Utility at system-definition time. To 
obtain reports about the station-list names and other entities defined for your system, 
refer to the COMS Configuration Guide. 


Programming Requirements 


Table F-19 shows the input parameters you pass to the GET STATION_LIST_ DESIGNATOR 
service function and the output parameters that the COMS library returns. The table 

also provides data types for the parameters in ALGOL and COBOL, and the values that 

can be returned by the service function call. 


Table F-19. GET_STATION_LIST_DESIGNATOR Parameters 


Direction Parameter COBOL Data Type ALGOL Data Type 
Input to COMS Station-list name COBOL74: Display '  EBCDIC array 


Output from Station-list COBOL74: Binary Integer 
COMS designator : 


continued 
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Station 
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Table F~19. GET_STATION_LIST_DESIGNATOR Parameters (cont.) 


Direction Parameter COBOL Data Type ALGOL Data Type 


Output from Function value The function value 0 is returned by the 
COMS . | GET_STATION_LIST_DESIGNATOR call if there 
is an invalid station-list name. 


For COBOL74, declare each variable as a PIC $9(11) (1-word) field. Declare the binary 
data type shown in Table F~19 at level 77, and the display data types at level 01. 


Examples 


Following are examples of COBOL and ALGOL code for calling the 
GET_STATION_ LIST DESIGNATOR service function from an application program or 
an agenda processing item: 


COBOL74 


CALL "GET_STATION LIST DESIGNATOR IN DCILIBRARY" 
USING <station-list name>, 
GIVING <station-list designator>. 


ALGOL 


<station-list designator> := 
GET_STATION_LIST_DESIGNATOR 
(<station-list name>) ; 


Names 


When you pass a station designator to the GET STATION NAME service function, the 
COMS library returns the following information: 

e Avvalid station name with a length of 1 to 255 alphanumeric characters. 

e A device designator for the station. 

e Astation-security designator. 

e A logical station number (LSN). If this number is 0, then the station is disconnected. . 
e Avirtual terminal. 
e Ascreen size. 


When you pass a message to a COMS direct-window program from the ODT using 
the format <mix # of COMS>SM PASS <window> <text>,COMS puts a station 
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designator in the input CD. The input CD passes the station designator to the 
GET_STATION_NAME service function, and then the COMS library returns ODT as a 
valid station name. 


Origin of Input Parameter 

You can obtain a station designator from either of the following sources: 

e The COMS-in-Station field of the input CD in an application program 

e The GET _STATION_DESIGNATOR service function 

Programming Requirements 

Table F—20 shows. the input parameters you pass to the GET_STATION_ NAME service 
function and the output parameters that the COMS library returns. The table also 


provides data types for the parameters in ALGOL and COBOL, and the values that can 
be returned by the service function call. 


Table F-20. GET_STATION_NAME Parameters 


Direction Parameter COBOL Data Type ALGOL Data Type 
Input to COMS Station designator COBOL74: Binary Integer 


Output from Station name COBOL74: Display EBCDIC array 
COMS 


Output from | Device designator COBOL74: Binary Integer 
COMS 


Output from | Station-security COBOL74: Binary Integer 
COMS designator 


Output from LSN COBOL74: Binary Integer 
COMS 


Output from Virtual terminal ~ COBOL74: Binary Integer 
COMS 


Output from Screen size COBOL74: Binary integer 
COMS 


continued 
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Table F-20. GET_STATION_NAME Parameters (cont.) 


Direction . Parameter COBOL Data Type ALGOL Data Type 


Output from Function value ‘The following function values can be returned by 
COMS the GET_STATION_NAME call: 


e 1 =Noerrors 
e 0 = One of the following has occurred: 
— An invalid designator was used 


— The station was no longer logged on to 
COMS 


For COBOL74, declare each variable as a PIC $9(11) (1-word) field. Declare the binary 
data type shown in Table F-20 at level 77, and the display data types at level 01. 


Examples 


_ Following are examples of COBOL and ALGOL code for calling the 
GET_STATION_NAME service function from an application program or an agenda 
processing item: 


COBOL74 


CALL "GET_STATION_NAME IN DCILIBRARY" 

USING <station designator>, 
<station name>, 
<device designator>, 
<LSN>, <virtual terminal>, <screen size> 
<station-security designator> 

GIVING <result of GET_STATION_NAME 

service function>. 


ALGOL 
<result of GET _STATION_NAME service function> := 
GET_STATION NAME (<station designator>, 


<station name>, <device designator>, <virtual terminal>, 
<screen size>, <LSN>, <station-security designator>) ; 


Message Date and Time 


You can use the GET_DATE service function to get the message date and time. 


When you pass a 1-word timestamp in TIME(6) format to this service function, the 
COMS library returns a six-character display field representing the time portion of the 
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timestamp. The six-character field displays the date in the month/day/year (MMDDYY) 
format, and the time in the hours/minutes/seconds (HHMMSS) format. 


Origin of Input Parameter 


You can obtain a timestamp from the COMS-in-Timestamp field in the input CD of an 
application program. 


Programming Requirements 


Table F-21 shows the input parameters you pass to the GET_DATE service function and 
the output parameters that the COMS library returns. The table also provides data 
types for the parameters in ALGOL and COBOL, and the values that can be returned by 
the service function call. 


Table F-21. GET_DATE Parameters 


Direction Parameter COBOL Data Type ALGOL Data Type 
Input to COMS Timestamp COBOL74: Binary Integer 


Output from Date COBOL74: Display EBCDIC array 
COMS 


Output from COBOL74: Display EBCDIC array 
COMS 


Output from Function value The following function values can be returned by 
COMS the GET_DATE call: 
e 1 = Noerrors 


e 0 = Invalid timestamp 


For COBOL74, declare each variable as a PIC $9(11) (1-word) field. Declare the binary 
data type shown in Table F-21 at level 77, and the display data types at level 01. 


Examples 


Following are examples of COBOL and ALGOL code for calling the GET_DATE service 
function from an application program or an agenda processing item: 


COBOL74 


CALL "GET_DATE IN DCILIBRARY" 
USING <timestamp>, 
<date>, 
<time>, 
GIVING <result of GET _DATE service function>. 
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ALGOL 


<result of GET DATE service function> := . | 
GET DATE (<timestamp>, <date>, <time>) ; 
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This glossary provides the definitions for selected terms used in this programming guide. The 
terms are presented in alphabetical order. 


A 


abort 
To terminate an active program or session abnormally and, sometimes, to attempt to 
restart it. 


ADDS 
See Advanced Data Dictionary System. 


Advanced Data Dictionary System (ADDS) 
A software product that allows for the centralized definition, storage, and retrieval of 
data descriptions. 


agenda 
An entity used for message routing that consists of a processing-item list and a 
destination. An agenda can be applied to messages that are received or sent by 
application programs. 


Agenda Processor library 
An internal library that applies processing items to messages by executing the 
prose ts lists that agendas specify. 


ALGOL 
' Algorithmic language. A structured, high-level programming language that provides 
the basis for the stack architecture of the Unisys A Series systems. ALGOL was the 
first block-structured language developed in the 1960s and served as a basis for such 
languages as Pascal and Ada. It is still used extensively on A Series systems, primarily 
for systems programming. 


‘audit trail 
In Data Management System IT (DMSID), a file produced by the Access routines that 
contains various control records and a sequence of before-update and after-update 
record images resulting from changes to the database. The audit trail is used to recover 
the database and supply restart information to programs after a hardware or software 
failure has occurred. 


audited database 
In Data Management System II (DMSID) and in the InfoExec environment, a database 
that stores a record of changes (called the audit trail), which can be used for database 
recovery if a hardware or software failure occurs. 
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B 


batch mode 
An execution mode in which a program running under COMS can do batch-type updates 
to a database shared by other transaction processors. 


BNA 
The network architecture used on A Series, B 1000, and V Series systems as well as 
CP 9500 and CP 2000 communications processors to connect multiple, independent, 
compatible computer systems into a network for distributed processing and resource 
sharing. 


C 


CANDE 
See Command and Edit. 


casual output 
Any output that is not protected from loss in the event of a system failure. 


CD 

See communication description. 
‘COBOL : 

Common Business-Oriented Language. A widely used, procedure-oriented language 
intended for use in solving problems in business data processing. The main 
characteristics of COBOL are the easy readability of programs and a considerable degree 
of machine independence. COBOL is the most widely used procedure-oriented language. 

Command and Edit (CANDE) 


A time-sharing message control system (MCS) that enables a user to create and edit 
files, and develop, test, and execute programs, interactively. 


communication description (CD) 
A message header passed with the message data received and sent by application 
programs that interface with a message control system (MCS). The CD provides routing 
information about the message data and allows use of other functions, depending on the 
MCS. 


Communications Management System (COMS) 
A general message control system (MCS) that controls online environments on A Series 
systems. COMS can support the processing of multiprogram transactions, single-station 
remote files, and multistation remote files. See also COMS (Full-Featured) and COMS 
(Kernel). 


Communications Processor 2000 (CP 2000) 
A data communications processor (DCP) that provides communications interfaces to local 
area networks (LANs) and wide area networks (WANs), including BNA Version 2 and 
Transmission Control Protocol/Internet Protocol (TCPIP) networks. The CP 2000 also 
provides connections to terminals controlled by BNA Version 2 software. 
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COMS 
See Communications Management System. 


COMS Control library 
A Communications Management System (COMS) internal library that initiates a 
database (DB) library for each database that uses synchronized recovery, and initiates 
a transaction processor (TP) library for nondatabase, transaction-processing programs 
that do not use synchronized recovery. 


COMS (Full-Featured) 
A version of the Communications Management System (COMS) message control system 
(MCS) that provides full configuration capabilities through the COMS Utility. The 
COMS Utility enables the user to define and customize’a COMS transaction processing 
environment, which provides additional features like transaction-based routing and 
database recovery. In addition, the user can track COMS statistics and use GEMCOS 
migration aids. 


COMS (Kernel) 
The transitional, temporary version of the Cotaticninaiaons Management System 
(COMS) message control system (MCS). COMS creates a predefined configuration file 
that enables the user to use the window feature with the following three windows: a 
Menu-Assisted Resource Control (MARC) window with eight dialogues, a Command and 
Edit (CANDE) window with two dialogues, and a Generalized Message Control System 
(GEMCOS) window with one dialogue. Additionally, the user can communicate with 
remote-file programs. 


COMS library 
The library that is created upon the execution of a FREEZE statement after the 
SYSTEM/COMS object code initiates as internal processes the Router library, the 
Agenda Processor library, and the COMS Control library. The COMS library contains 
service functions for designator conversion, dynamic selection procedures for linking 
callers to other libraries within the COMS system, and support for dynamic table 


changes. 


COMS network 
A system of interconnected elements consisting of at least one computer system and one 
or more stations for which the Communications Management System (COMS) provides 
communication and processing control. 


COMS tables 
The forms and data that comprise the information defined and maintained by means 
of the COMS Utility. These forms are included in the Communications Management 
System (COMS) configuration file. 


COMS Utility 
The Communications Management System (COMS) program that defines and maintains 
the specifications stored in the COMS configuration file. 


| configuration file 


A file that contains descriptions of the tables defined through th the COMS Utility 
program. These tables contain information on message routing, security, dynamic 
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program control, and synchronized recovery. This file is also referred to as the COMS 
CFILE. 


conversation area 
The user data space in the header of a message. The conversation area is user defined 
and can contain information passed by a program or processing item. When used with a 
direct-window interface, this area contains the telephone number to be dialed. 


CP 2000 
See Communications Processor 2000. 


current transaction 
In Data Management System II (DMSI)), the transaction that is attempting to update 
the database at the moment that a transaction-state abort or system failure occurs. 


D 


DASDL 
See Data and Structure Definition Language. 


Data and Structure Definition Language (DASDL) 
In Data Management System IT (DMSID), the language used to describe a database 
logically and physically, and to specify criteria to ensure the integrity of data stored in 
the database. DASDL is the source language that is input to the DASDL compiler, which 
creates or updates the database description file from the input. 


data comm 
See data communications. 


data communications (data comm) 
The transfer of data between a data source and a data sink (two computers, or a 
computer and a terminal) by way of one or more data links, according to appropriate 
protocols. 


data communications interface (DCD) library 
‘A library that serves as the direct programmatic interface to the Communications 
Management System (COMS). Application programs must communicate with COMS 
through the DCI library to use agendas, processing items, routing by trancode, and 
synchronized recovery. 


Data Management System II (DMSII) 
A specialized system software package used to describe a database and maintain the 
relationships among the data elements in the database. 


database (DB) 
An integrated, centralized system of data files and program utilities designed to support 
an application. The data sets and associated index structures are defined by a single 
description. Ideally, all the permanent data pertinent to a particular application resides 
in a single database. The database is considered a global entity that several applications 
can access and update concurrently. 
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DB 
See database. 


DB control program 
A process that initiates all application programs using synchronized recovery with a 
database and detects transaction-state aborts that occur during the processing of the 
database. Each database being synchronized has its own DB control program. 


DB library 
The data communications interface (DCD) library for programs that are controlled by a 
common database (DB) control program. 


DCI library 
See data communications interface (DCI) library. 


DCIENTRYPOINT 
An entry point of the data communications interface (DCI) library. A compiler 
automatically generates code calling this entry point whenever an application program 
executes an ENABLE, RECEIVE, or SEND statement. 


DCIWAITENTRYPOINT 
An entry point of the data communications interface (DCD) library. An ALGOL 
application can call DCIWAITENTRYPOINT when the application is waiting for the DCI 
input to arrive and other independent, application-visible events to happen. 


default 
Pertaining to a value automatically assigned by a program or system when another value 
has not been specified by the user. 


default agenda 
The agenda that the Communications Management System (COMS) applies to a 
message if the message does not contain a trancode, or if the message contains a 
trancode value that has not been defined for the system. A default agenda is assigned 
to each direct window with the COMS Utility program. There can be one default input 
agenda and one default output agenda for each window. 


designator 
A binary number that is part of an internal code used in the table structure. By 
- using designators in programs that run under COMS, the programmer can control 
messages symbolically rather than by communicating directly with entities in the data 
communications environment. 


direct window 
A type of window that enables the user to route messages directly to COMS, while using 
all the COMS capabilities for preprocessing and postprocessing of messages. 


DMSII 
See Data Management System II. 


DMSII recovery 


In Data Management System I (DMSI)), a database routine that is initiated after a 
hardware, software, or operations failure while a database is in the update mode. DMSII 


8600 0650-000 | Glossary-5 


Glossary 


recovery backs out any partially completed transactions by applying audit-trail images to 
the database to restore it to its proper state. It also passes restart information to the 
programs accessing the database. 


DMTERMINATE procedure 
A system-level Data Management System II (DMSID procedure that a database 
processing program can invoke at any time to display a standard, recognizable error 
message and to discontinue the program. 


E 


EBCDIC 
Extended Binary Coded Decimal Interchange Code. An 8-bit code representing 256 
graphic and control characters that are the native character set of most mainframe 
systems. 


EBCDIC array 
In ALGOL, an array whose elements are EBCDIC characters. 


echo program 
A simple program that echoes or returns input messages as output. The input source 
and output destination can be any devices defined in the program. 


element 
A specifically defined item within an entity category of the configuration file. 


enabled 
Referring to a station that is being polled (invited to transmit in a certain order) and that 
can communicate with the system. 


end of file (EOF) 
A code at the end of a data file that signals that the last record in the file has been 
processed. 
end of job (EOJ) . 
The control code that signals the receiver that a job has completed. 
end of task (EOT) . 
The termination of processing of a task. 
entity 
A category of items within the configuration file. 
entry point . 
A procedure or function that is in.a library object. 
EOF 
See end of file. 
EOJ 
See end of job. 
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EOT 
See end of task. 


EXCEPTIONTASK 
A task-valued task attribute that the operating system sets by default to the parent task. 
The EXCEPTIONTASK attribute is used to link an application program to the data 
communications interface (DCD library of the Communications Management System 
(COMS) during program initialization. 


F 


file switch 
The act of stopping the processing on one file and starting the processing on another file. 
This switch can be done automatically by the system or manually by the user. 


G 


GEMCOS 7 | 
See Generalized Message Control System. 


Generalized Message Control System (GEMCOS) 
_A message control system (MCS) developed for online systems. GEMCOS is transaction 
oriented. 


H 


halt/load 
A system-initialization procedure that temporarily halts the system and loads the 
operating system from a disk to main memory. 


header 
A sequence of characters preceding the text of a message, containing routing or other 
communications-related information. 


installation 
A single computer configuration, facility, center, or system consisting of one or more 
mainframes and any possible combination of peripheral, communications, I/O, and other 
types of support devices. 


INVALID OP 


An error that occurs when a character or sequence of characters is not in accordance 
with the expected character or sequence. 
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library 
A collection of one or more named routines or library objects that are stored in a file and 
can be accessed by other programs. 


logical station number (LSN) 
In Network Definition Language II (NDLID), a unique number assigned to each station 
in anetwork. Each station has an LSN assigned according to the order in which the 
stations are defined in NDLII. The first defined station is 0000. 


LSN 
See logical station number. 


M 


MARC 
See Menu-Assisted Resource Control. 


Master Control Program (MCP) 
An operating system on A Series systems. The MCP controls the operational 
environment of the system by performing job selection, memory management, peripheral 
management, virtual memory management, dynamic subroutine linkage, and logging of 
errors and system utilization. 


MCP 
See Master Control Program. 


MCS 
See message control system. 


Menu-Assisted Resource Control (MARC) 
A menu-driven interface to A Series systems that also enables direct entry of commands. 


message 
Any information-containing data unit, in an ordered format, sent by means of a 
communications process to a named network entity or interface. A message contains 
the information (text portion) and controls for routing and handling (header portion). 
In Data Communications ALGOL (DCALGOL), a special form of array. Two types 
of messages are recognized by a message control system (MCS): those used with 
DCALGOL DCWRITE statements and those generated elsewhere in the data 
communications subsystem that appear in an MCS queue. 


message control system (MCs) 
A program that controls the flow of messages between terminals, solicating programs, 
and the operating system. MCS functions can include message routing, access control, 
audit and recovery, system management, and message formatting. 


message header 


A sequence of characters, preceding the text of a message, that contains routing or 
descriptive information for the message. 
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MFI 
See module function index. 
MLS 
See multilingual system. 
module function index (MFI) 
An integer value that represents a transaction code or group of transaction codes that 
are used to route forms or messages. 
Muleiiingual System (MLS) 


An environment that can process information using the standards and functional 
requirements of different localities, cultures, or lines of business. The processing of 
information depends on the ccsversion, languages, and conventions that are defined for 
the system. For example, output messages, online help text, menus, and screens can 
be developed and accessed in different natural languages, such as English, French, or 
Japanese. 


multiprogram environment 
An environment in which a software system handles multiple routines or programs 
simultaneously by overlapping or interleaving their execution, permitting more than one 
program to timeshare machine components. 


N 


NDLII 
See Network Definition Language IT. 


Network Definition Language I (NDLI) | 
The Unisys language used to describe the physical, logical, and functional characteristics 
of the data communications subsystem to network support processors (NSPs), line 
support processors (LSPs), and data communications data link processors (DCDLPs). 


network support processor (NSP) 
A data communications subsystem processor that controls the interface between a host 
system and the data communications peripherals. The NSP executes the code generated 
by the Network Definition Language IT (NDLID compiler for line control and editor 
procedures. An NSP can also control line support processors (LSPs). 


NSP 
See network support processor. 


P 


parameter 
An identifier associated in a special way with a procedure. A parameter is declared in the 
procedure heading and is automatically assigned a value when the procedure is invoked. 
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Pascal 
A high-level programming language developed by Niklaus Wirth, based on the block 
structuring nature of ALGOL 60 and the data structuring innovations of C.A.R. Hoare. 
Pascal is a general-purpose language. 


password 
A character string associated with a usercode or accesscode in the USERDATAFILBE, 
and used to identify legitimate users of the system. When logging on to a message 
control system (MCS), a user must supply a usercode and a password. 


peripheral 
A device used for input, output, or file storage. Examples are magnetic tape drives, disk 
drives, printers, or operator display terminals (ODTs). Synonym for peripheral device. 


POF 
See protected output file. 


postprocessing 
The processing done to a message by processing items after an application program 
sends out the message. 


preprocessing 
The processing that the Agenda Processor performs on a message before an application 
program receives the message. 


process switching 
An event that occurs when the operating system tells the central processing unit (CPU) 
to execute a different program. 


processing item 
A procedure, contained in a processing-item library, used for processing a message. 


processing-item library 
A user-written ALGOL library containing a set of procedures called processing items. 
A processing-item library can be called only by the COMS Agenda Processor library to 
preprocess and postprocess messages as they are received and sent by programs. 


protected database 
A database that is associated with a protected window. 


protected dialogue 
A dialogue on a protected window, which has the protected output feature enabled. 


‘protected output feature 
A feature that enables output messages to be written to a disk file and then sent to their 
destinations only after successful completion of the transaction. 


protected output file (POF) 


A disk file that contains protected output messages. These messages are sent to their 
destinations after a transaction has been completed. 
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protected window 
A window that has the protected output feature enabled. 


Q 


queue 
A data structure used for storing objects; the objects are removed in the same order they 
are stored. In Data Communications ALGOL (DCALGOL), a linked list of messages. 


R 


remote file 
A file with the KIND attribute specified as REMOTE. A remote file enables object 
programs to communicate interactively with a terminal. 


Remote Print System (ReprintS) 
A Unisys software system that controls the routing and printing of backup files at 
remote (data comm) destinations and on BNA networks. 


Report Program Generator (RPG) 
A high-level commercially oriented programming language used most frequently to 
produce reports based on information derived from data files. 


ReprintS . 
See Remote Print System. 


reproducibility 
The ability of a sequence of transactions to be reproduced under-the same conditions and 
to achieve the same results as the original transactions. 


restart 
To return to a particular point in a program and resume operation from that point. 


restart data set (RDS) 
In Data Management System IIT (DMSID, a data set containing restart records that 
application programs can access to recover database information after a system failure. 


restart record 
_ Arecord containing information stored by update programs that enables the programs 
to restart in response to particular conditions. For each update program, COMS saves 
restart records in the transaction trail along with the eee images of the input 
header and the message data. 


restartable application program . 
An application program that can resume processing automatically after an interruption | 
such as a halt/load or an abort. 


rollback 


The recovery of a database or transaction base to a consistent state at an earlier point in 
time. . 
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Router library 
An internal library containing input-router and outpubrouter entry points called by the 
Master Control Program (MCP). The input-router entry point is primarily called by the 
data communications controller (DCC) for all input-message and output-message results 
associated with any station controlled by COMS. The output-router entry point is called 
from logical I/O for output from remote files. 


RPG . 
See Report Program Generator. 


S 


Screen Design Facility (SDF) 
The InterPro product used for creating forms for online, transaction-based application 
systems. 


SDF 
See Screen Design Facility. 


security category 
A designation that provides access security for programs, stations, transaction codes, and 
usercodes. Up to 32 security categories can be defined for an installation. 


security-category list 
A group of several security categories that can be assigned to certain entities to 
accomplish forms of security. 


Semantic Information Manager (SIM) 
The basis of the InfoExec environment. SIM is a database management system used 
to describe and maintain associations among data by means of subclass-superclass 
relationships and linking attributes. 


service function 
An integer procedure of the Communications Management System (COMS) tibrary that 
enables the user to access subroutines that can do the following: translate a designator 
to a name that represents a COMS entity; translate a name that represents a COMS 
entity toa designator; or obtain additional information about the name or designator 
passed to the service function. 


session security | 
The intersection of the security categories assigned to a station and the security 
categories assigned to the usercode of the person who is logged on to that station. 


SIM 
See Semantic Information Manager. 


stack 


A region of memory used to store data items in a particular order, usually on a last-in, 
first-out basis. Synonym for process stack. 
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state 
The condition of one or all the units or elements of a computer system. 
station 
A data structure that relates a logical connection to either a terminal device or a 
pseudostation. 
string 
A connected sequence or group of characters. 
subroutine 


A self-contained section of a program to which program control is transferred when the 
subroutine is invoked and that transfers control back to the point of invocation when it is 
exited. 


synchronized recovery 
A function that resubmits incomplete transactions to the database after a 
transaction-state abort, system crash, or rollback occurs. This COMS function is called 
synchronized recovery because it reprocesses transactions in the same order that they 
were originally processed by multiple programs running asynchronously, even if the 
transactions were conflicting. 


syncpoint | 
_ In Data Management System IT (DMSID, a eal in time when no program is ina 
transaction state. 

syntax 


The rules or grammar of a language. 


T 


tanked messages 
Incoming messages that are being deferred from display at a station because the 
associated window is suspended. 


task 
A single, complete unit of work performed by the system, such as compiling or executing 
a program, or copying a file from one disk to another. Tasks are initiated by a job, by 
another task, or directly by a user. 

TBR 
See transaction-based routing. 

terminal 
An I/O device designed to receive or send source data in a network. 

text 


The part of a message containing information that has an ultimate purpose and 
destination beyond the data communications subsystem. 
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throughput 
The total useful information processed during a specified time period. 


TIME(6) format . 
In ALGOL, a system format that returns a unique number representing the time and 
date (a timestamp) in the following form: 0 & (JULIANDATE — 70000) [47:16] & 
(TIME (11) DIV 16) [81:32] 


timestamp 

An encoded, 48-bit numerical value for the time.and date. Various timestamps are 
maintained by the system for each disk file. Timestamps note the time and date a file 
was created, last altered, and last accessed. 


TP library 
See transaction processor (TP) library. 


TP-to-TP message 
Any output message directed to a program. 


TPS 
See transaction processing system. 


trancode 
See transaction code. 


transaction 
The transfer of one message from a terminal or host program to a receiving host 
program, the processing carried out by the receiving host program, and the return of an 
answer to the sender. 


transaction code (trancode) 
A code that can appear in a transaction-initiating message header, indicating the 
processing that is to be carried out. This code is used to route the message to the 
appropriate host program. 


transaction processing system (TPS) 
A Unisys system that provides methods for processing a high volume of transactions, 
keeps track of all input transactions that access the database, enables the user to batch 
data for later processing, and enables transactions to be processed on a database that 
resides on a remote system. 


transaction processor (TP) library 
The data communications interface (DCD) library for application programs that use the 
Communications Management System (COMS). 


transaction state 
In Data Management System II (DMSI)), the period in a user-language program 
between a begin transaction operation and an end transaction operation. 


transaction trail 


A file maintained by a Communications Management System (COMS) database (DB) 
library that contains a series of time-ordered transactions that can be reapplied to the 
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database to provide synchronized recovery in the event of a transaction-state abort, 
system crash, or rollback. The file can also be used to provide a journal of both query 
and update transactions for security auditing, accounting, and statistical reporting. Each 
DB library has its own transaction trail. 


transaction-based routing (TBR) 
A Communications Management System (COMS) capebiy. that routes messages 
according to the transaction codes they contain. 


two-phase transaction 
A transaction in which the first execution phase locks records without freeing any, the 
second and final execution phase of the transaction frees records without locking any, 
and no records are retrieved without locking them. 


U 


update 
To delete, insert, or modify information in a database or transaction base. 


usercode . 
An identification code used to establish user identity and control security, and to provide 
for segregation of files. Usercodes can be applied to every task, job, session, and file on 
the system. A valid usercode is identified by an entry in the USERDATAFILE. 


USERDATAFILE 
A system database that defines valid usercodes and contains various data about each 
user (such as accesscodes, passwords, and chargecodes) and the population of users for a 
particular installation. 


V 


virtual terminal (VT) 
A terminal attribute that identifies the text postprocessing algorithm to be applied to 
data messages sent to the terminal. 


VT 

See virtual terminal. 
WFL 

See Work Flow Language. 
window 


The concept that enables a number of program environments to be operated 
independently and simultaneously at one station. One of the program environments can 
be viewed while the others continue to operate. 
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word 
A unit of computer memory. On A Series systems, a word consists of 48 bits used for 
storage plus tag bits used to indicate how the word is interpreted. 

Work Flow Language (WFL) 


A Unisys language used for constructing jobs that compile or run programs on A Series 
_systems. WIL includes variables, expressions, and flow-of-control statements that offer 
the programmer a wide range of capabilities with regard to task control. 
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CLOSE command, 6-9 
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6-12 ; . 
dynamic remote-file windows, 9-1 
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echo program 

presented as sample direct-window 

program, C-—2 

EGI, (See end-of-group indicator (EGD) 
EMI, (See end-of-message indicator (EMI) 
ENABLE INPUT statement 

used in sample program, C-8, C-11 
ENABLE PROGRAM, 2-2 
ENABLE WINDOW, 2-2 
end-of-group indicator (EGD), 3-28 
end-of-message indicator (EMI), 3-23 
end-of-segment indicator (ESD, 3-23 
END-TRANSACTION statement 

effect of order of occurrence, 6-9 
entry points, 4~—1 
ENTY_NAME 

station names, 4-12. 
ESI, (See end-of-segment indicator (ESD) 
exception-condition statements 

using at database close, 6-12 
exclusive lock, 6-5 
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form key 

used in Conversation Area field, 3-17 
FORM-KEY identifier 

referencing the required SDF form, C-9 

used in sample program, C-8, C-9, C-11 
formlibrary, (See SDF formlibrary) 
formlibrary Definition screen 

options to choose for direct-window 

program, C~8 

FREEZE attribute, 5—4 
Function Index field, 3-5 
Function Status field, 3-5 

for Module Function Index error, 3-12 
function status values and mnemonics, A-1 
Function values 

defining, D-7 
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generated formlibrary name, C-5 
GET_AGENDA DESIGNATOR service 
function, F-1, F-2 
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GET _AGENDA_ NAME service function, 
F-2, F-3 

GET_DATE service function, F-30, F-31 

GET DESIGNATOR ARRAY _ 
USING_DESIGNATOR service 
function, 4-8 

GET_DESIGNATOR USING __ 
DESIGNATOR service function, 
4-8 

GET DESIGNATOR USING _NAME service 
function, 4-3, 4-9 

calling in direct-window program to obtain 

agenda designator, C-6 

GET_DEVICE DESIGNATOR service 
function, F~7, F-8 

GET_DEVICE_ NAME service function, F-8, 
F-9 

GET_INTEGER ARRAY USING __ 
DESIGNATOR service function, 
4-10 

GET_INTEGER USING DESIGNATOR 
service function, 4-10 

GET_NAME USING_DESIGNATOR service 
function, 4-11 

GET PROGRAM _ DESIGNATOR service 
function, F-10 

GET_PROGRAM_NAME service function, 
F-11 

GET PROGRAM SECURITY_ 
DESIGNATOR service function, 
F-13, F-14 

GET_REAL ARRAY service function, 4-12 

used to access COMS statistics, 4-12 

GET_SECURITY_CATEGORY_ 
DESIGNATOR service function, 
F—14, F-15 

GET STATION ATTRIBUTES service 
function, F-23, F-24 

GET_STATION_DESIGNATOR service 
function, F-25 

GET_STATION_LIST service function, F~26 

GET STATION LIST DESIGNATOR | 
service function, F—27, F-28 

GET_STATION: NAME service function, 
F-28, F-29 

GET_ STATION SECURITY_ 
DESIGNATOR service function, 
F-16, F-17 

GET _STRING_USING_ DESIGNATOR 
service function, 4-13 

GET_USER service function, F-18, F-19 
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GET_USER_DESIGNATOR service 
function, F-17, F-18 
GET_USER_ SECURITY DESIGNATOR 

service function, F-20, F-21 

GET _WINDOW_DESIGNATOR service 
function, F-4, F-5 

GET_WINDOW_INFO service function, F-4, 
F-5, F-6 


H 


header fields 
input, 3-4 
output, 3-14 
HEADER parameter 
definitions and functions of, 5-8 
headers 
input 
using to get program to receive 
messages, 3-4 
multiple 
declaring within sample programs, 3-17 
l 
INDEPENDENTTRANS option, 6-2 
initializing . 
a direct-window program, 3-3 
input events, 3-9 
input header 
using, 3-4 
input header fields, 3-4 
Agenda Designator, 3-7 
Conversation Area, 3-7 
Function Index, 3-5 
Function Status, 3-5 
values and mnemonics of, A-2 
Message Count, 3-7 
Program Designator, 3-5 
Restart, 3-7 
SDF Information, 3-7 
Security Designator, 3-5 
Station Designator, 3-6 
Status Value, 3-6 
Text Length, 3-6 
_ Timestamp, 3-6 
Transparent, 3-6 
Usercode Designator, 3-5 
VT Flag, 3-6 
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input header parameters 
defining, D-6 
input headers 
using in security checking, 8-1 
input messages 
checking the status of, 3-13 
input queue 
processing, 6-10 
protection, 6-1 
INPUT ROUTER 
specifying as an agenda, 5-3 
using to route by trancode, 3-28 


' installation data 


mnemonics for, 4—5 
used to attach configuration elements, 4-3 
installation data entity items 
accessing with service function calls, 4-4 
interactive recovery, 6-1 
preparing to use, 6-2 
programmatic conventions, 6-3 
requirements for using, 6-7 
using DMSI 
program flow example, 6-14 
using SIM 
program flow example, 6-19 
with DMSII databases, 6-9 
writing programs that use DMSII, 6-11 
interactive recovery programs 
with SIM databases, 6-19 
INVALID OP error, 6-4 


K 


Kernel version of COMS, 1-1 
KEY DIAL, 3-31 
KEY NOWAIT option, 3-32 
key options 
on attachment, 3-31 
on detachment, 3-32 
KEY WAIT option, 3-32 
KEY WAITDIALODT option, 3-32 
KEY WAITNOTBUSY option, 3~32 
keydata 
in a database, 3-3 
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LASTSTATION attribute, 9-2 
libraries 
processing-item 
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creating in ALGOL, 5-4 
library configuration 
choosing, 5-5 
locking phase 
of a two-phase transaction, 6-5 


M 


MCS windows 
applications, 2~—2 
message area 
preparing, 3-2 
space requirements for, 3-2 
using to receive an SDF form, 3-2 
Message Count field, 3-7, 3-8 
placing queued messages in, 3-8 
message data 
altering procedure by processing items, 
5-2 
message origin 
determining from the input header, 3-11 
message processing 
as a COMS feature, 1-2 
message routing 
as a feature of COMS, 1-3 
message truncation 
avoiding within the receive area, 3-4 
messages ; 
determining origin of, 3-11 
Message Value tables 
mnemonic tables, A-1 
output 
method of formatting, 5-14 
programming to receive, 3-4 
programming to send, 3-13 
queued 
detecting, 3-8 
routing 
decision table for, 3-22 
logic for, 3-21 
specifying a destination, 3-24 
mnemonic tables, A-1 
mnemonics 
explanation for use with installation data, 
4-5 
modifying the COMS configuration file, 2-5 
module function index (MFT) 
in Function Index field, 3-5 
with input, 3-12 
Module Function Index (MFT) 
purpose within sample program, C-9 
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use in programmatic security checking, 8-2 
Module Index 
SDF term for Module Function Index, C-8 
multiple headers 
declaring 
within sample programs, 3-17 
multiuser declared windows, 9-3 
MYUSE=OUTPUT 
using NDLII to define a printer 
as a single-output window, 8-4 


N 


NDLIJ, (See Network Definition Language IT 
(NDLID) 

Network Definition Language IT (NDLID), 84 

Next Input Agenda Designator field, 3-15 

notify-on text, C-2 

notify-open text, C-2 


O 


obtaining designators, 3-14 

offsets 
defining for direct-window programs and 

message keys, C-8 

On Notification text, 3-12 _ 

Open Notification text, 3-12 

origin of a message 
determining, 3-11 

out-of-band error 
when an output message is rejected, 3-30 

output header fields, 3-14 

output header parameters 
defining, D-6 

output messages 
checking the status of, 3-30 
formatting, 5-14 

OUTPUT _PROC parameter, 5-10 

OUTPUT _PROC procedure 
calling to transmit a message, 5-11 
defined, 3-14 . 
passing an input header to, 5-12 
passing an output header to, 5-13 
passing the parameters to, 5-12 
specifying a processing item with, 3-14 
uses for, 5-11 - 
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parameters 
input header ' 
methods of defining, D-6 
output header 
methods of defining, D-6 
STATE 
methods of defining, D-7 
TITLE, D-1 
postprocessing 
by specifying an agenda, 5-1 
definition of, 3-25 
how COMS routes a message for, 5-2 
preparing a message area, 3~2 
preprocess 
definition of, 5—1 
preprocessing 
how COMS routes a message for, 5-2 
processing item 
creating 
by using ALGOL specifications, 5-6 
processing items, 5-1 
altering carriage control with, 5-14 
altering message data, 5-2 
applying to messages, 5-1 
decisions to made before using, 2-3 
example of postprocessing, 5-4 
examples, D-1 
formatting output messages with, 5-14 
possible uses for, 5-1 
providing for results, 5-16 
providing for the result returned by, 5-16 
STATUS LINE, D-10 
TPTOMARC, D-8 
used to pass input headers to 
OUTPUT_PROC, 5~12 
used to pass output headers to 
OUTPUT_PROC, 5-13 
using as SDF form, C-8 
using the ALGOL specification for 
creating, 5-6 
processing-item libraries 
choosing a configuration for, 5-5 
conventions for creating, 5-4 
creating in ALGOL, 5—4 
example with multiple entry points, 5-5 
processing-item results 
providing, 5-16 
PROC _ITE 
purpose within SDF formlibrary, C-5 
PROC_ITEM.[07:08] 
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definitions of associated values, 5-16, 5-17 — 
PROC_ITEM.[47:39] 
definitions of associated values, 5-17 
Program Designator field, 3-5, 3-11 
for database recovery, 3-5 
Program entity 
in configuration file, 4-1 
program use of COMS features, 2-5 
program-specified input agendas, 3-28 
program-to-program message 
how COMS routes for postprocessing, 5-3 
process-security 
conventions for, 8-4 
program-to-station message 
how COMS routes for postprocessing, 5-2 
process-security conventions for, 8-4 
programmatic conventions 
‘ general kinds of, 6-3 
programmatic security, 8-1 . 
checking 
using the input header for, 8-1 
when to use, 8-1 
programming to receive messages, 3-4 
programs 
failure 
COMS actions, 6-5 
initializing direct-window type, 3-3 
remote file, 2-2 
writing using batch recovery 
with concurrency, 7-11 
without concurrency, 7-3 
protected input queue, 6-1 


Q 


queued messages, 3-8 


R 


real array size, 4-13 
REAL PROCEDURE OUTPUT_PROC 
declaration of, 5-10 
REAPPLYCOMPLETED option, 6-2 
receive area 
preventing message truncation from 
within, 3-4 
RECEIVE statement 
used in sample program, C4, C-8 
receiving messages, 3~3, 3-11 
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record-level locking, 6-5 
recovery 
batch 
considerations for, 7-1 
interactive 
preparing to use, 6-2 
recovery components 
of COMS Utility, 6-1 
recovery methods 
database, 2-4 
recovery procedure 
components that facilitate, 6-8 
recovery programs using DMSII 
program flow for, 6-13 
recovery record, 6-9 
REDEFINES clause 
used in sample program, C—10 
relative station numbers 
associated with remote files, 9-2 
remote-file program, 2—2 
remote-file windows 
designation of input or output files, 9-4 
exception handling, 9-4 
programming notes for, 9-3 
tanking and multiuser remote-file 
windows, 9-4 
when to use, 9-1 
restart class, 7-11 
restart data set, 6-7 
creating, 6-11 


Data and Structure Definition Language, 


6-11 
spanning sets on, 6-12 
Restart field, 3-7 
Result action values 
defining, D-7 
Retain Transaction Mode Denenatee field, 
3-16 
Router library, 3-28 
role in message routing, 5-2 
routing by trancode 
used in sample program, C-8 
routing methods 
trancode, 2-4 
transaction-based, 1-3 


Ss 
SAME RECORD AREA clause 


explanation of, C~-9 
used in sample program, C-10 
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sample COBOL74 programs, C—1 
sample programs 
types presented, C—1 
Screen Design Facility (SDF) 
error messages, 3-12 
SDF form 
as a processing item in direct-window 
program, C~4 
SDF formlibrary 
declaring in direct-window program, C—5 
regenerating when recompiling a 
direct-window program, C-6, C-10 
SDF formlibrary declaration 
used in sample program, C-8, C-10 
SDF Information field 
input header, 3-7 
output header, 3-16 
security, (See programmatic security) 
defining measures for direct windows, 1-4 
programmatic, 8-1 
security categories, F-12 
security designator, 8-2 
Security Designator field, 3-5 
security errors, 8-5 
security level, F-12 
security scheme 
what to consider during Sidiae 2-3 
segmented message 
transmitting to a single destination, 5~-11 
segmented output, 3-23 
send before receive using trancode, 3-28 
SEND statement 
used in sample program, C-4, C-8, C-11 
sending messages, 3-13 | 
specifying a destination, 3-24 
using to route by trancode, 3~24 
service function calls 
using to access installation data entity 
items, 4—4 
service function result values and mnemonics, 
A-14 
service function security category values and 
mnemonics, A-15 
service functions, 4—1 
accessing, 4~1 
agenda designator, F—1, F-3 
agenda name, F—1, F—2 
call result messages, A-14 
calling, 4-6 
convert timestamp, 4-7 
device-type designator, F—7 
device-type name, F-8 
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GET_DESIGNATOR ARRAY 
_USING_DESIGNATOR, 4-8 
GET_DESIGNATOR USING _ 
DESIGNATOR, 4-8 
GET_DESIGNATOR_USING_NAMEB, 4-9 
GET INTEGER ARRAY_ 
USING_DESIGNATOR, 
4—10 
GET_INTEGER USING_DESIGNATOR, 
4-10 
GET_NAME USING DESIGNATOR, 
4—11 
GET_REAL_ARRAY, 4-12 
GET_STRING_USING_DESIGNATOR, 
4-13 
input parameter, 4—2 
message date, F~30 
output parameter, 4~2 
program designator, F-10 
program name, F-11 : 
program-security designator, F-11, F-13 
security-category designator, F-14 
security-category testing, F-21 
station attributes, F-23 
station designator, F—25 
station list, F~26 
station name, F-28 
station table, 4—7 
station table add, 4-14 
station table initialize, 4-14 
station table search, 4—15 
station-list designator, F-27 
station-security designator, F-16 
test designators, 4-15 
time, F-30 
user maximum per window, F—-4, F-5 
usercode designator, F-17 
usercode security-category-list designator, 
F-20 
usercode-security designator, F-18 
using designators within, 4-2 
using to obtain entity information, 4—1 
window designator, F-4 
Set Next Input Agenda field, 83-15 
SET TRANSACTION MODE attribute, 3-26 
SHAREDBYRUNUNIT library sharing 
option, 5-4, C-5 
SHARING option 
setting in processing-item libraries, 5-4 
SIM database 
in recovery, 6-2 
single-user declared windows, 9-2 
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spanning set 

on the restart data set, 6-12 
SPECIAL-NAMES paragraph 

used in sample program, C~10 
STATE parameter 

declaration 

in OUTPUT _PROC procedure, 5-6 
in PROC_ITEM procedure, 5-6 

definition and functions of, 5-7 

values associated with fields in word, 5-7 
STATE parameters 

defining, D-7 
STATE.[07:08], 5-7, 5-12 

definitions of associated values, 5-7 

occasions for use, 5-13 
STATE.[13:06] 

definitions of associated values, 5-7 
STATE.[15:02], 5-7 

definitions of associated values, 5-7 

occasions for use, 5-10 . 
STATE.[23:08] 

definitions of associated values, 5-8 
STATE. [47:24] 

definitions of associated values, 5—8 . 
Station Designator field, 3-6, 3-11 
station entity 

in configuration file, 4-1 

obtaining information, F-22 
Station List entity 

in configuration file, 4-1 
station search service functions 

definition of, 4—7 
station table add service function, 4-14 
station table initialize service function, 4—14 
station table search service function, 4-15 
stations 

attaching dynamically to, 3-31 

dynamically detaching from, 3-32 
statistics 

as an allowable mnemonic of the 

GET_REAL_ ARRAY, 4-12 

statistics mnemonic 

functions of, 4-12 
Statistics window, 1-4 
status checking 

input messages, 3-13 

output messages, 3-30 
STATUS LINE processing item, D-10 
Status Value field 

for Module Function Index (MFI), 3-12 

in determining message origin, 3-11 

in message routing, 3-25 
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input header, 3-6, 3-8 
- output header, 3-14 
using to check message status, 3-30 
values and mnemonics 
input header, A-8 
output header, A-11 
synchronized recovery, 6-9 


T 


tanking, 9-4 
task events, 3-9 
termination routine 
standard routine for COBOL74 programs, 
C-2 . 
termination time limit 
specifying in COMS Utility, C-3, C-6, C-10 
TEST_DESIGNATORS service function, 
4-15 
using in programmatic security checking, 
84 
TEST_SECURITY_CATEGORY service 
function, F-21 
Text Length field 
input header, 3~-6 
output header, 3-14 — 
TEXT_1 parameter 
definition and functions of, 5-10 
TEXT_2 parameter 
definition and functions of, 5-10 
TIME (6) system format, 3-6 
Timestamp field, 3-6 
TITLE parameter 
code used for setting, D-1 
TP library, (See transaction processor 
library) 
TPTOMAERC processing item 
coding scheme that defines, D-8 
parameters used by, D-6 
required values for, D-7 
trancode routing 
areas to consider before using, 2-4 
trancodes, 1-3, 3-27 
associated with module function index, 
3-12 . 
send before receive, 3-28 
transaction mode 
agenda, 3-27 
clearing, 3-27 
transaction processor library, 6-8 
transaction state 
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using SEND and RECEIVE statements 
within, 6-3 
transaction trail, 6-8 
transaction-based routing 
description of, 1-3 
TRANSACTION-MODE AGENDA attribute, 
3-26 
transactions, 6-4 
reprocessing aborted, 6-10 
transaction state, 6-4 
transaction-state abort detection by DB 
control, 6-8 
updating database, 6-3 
Transparent field 
input header, 3-6 
output header, 3-15 © 
transparent mode, 3-6, 3-15 
two-phase transaction, 6-1, 6-5 


U 


updating phase 

of a two-phase transaction, 6-5 
USERCODE attribute, 9-2 
Usercode Designator field, 3-5 

in programmatic security checking, 8—2 
usercode entity . 

in configuration file, 4-1 
USER_DATA parameter 

definitions and functions of, 5-9 
Utility, (See COMS Utility) 


V 


values 
function 
methods of defining, D~7 
result action 
methods of defining, D-7 
versions of COMS, 1-1 
Full-featured, 1-1 
Kernel, 1-1 
virtual terminal name, 3-29 
VT flag bit, 3-29 
VT flag field 
output header, 3-15 
VT Flag field 
input header, 3-6 
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window dialogues 

manipulating closed, 3-13 
Window entity 

in configuration file, 4—1 
windows 

available in COMS, 1-2 

COMS statistics, 1-4 

declared remote-file, 9-2 

dynamic remote-file, 9-1 
writing two-phase transactions, 6-5 


?DISABLE PROGRAM < program name> 
command 
using to terminate a direct-window 
program, C-3, C-6, C—10 
?ON <window name> command 
using to initiate a direct-window program, 
C-3, C-6, C-9 
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